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 #include "netapi.h"
55 /**
56 * @ingroup cfg_structures
57 * @brief CPPI flow ID for default case, use NETCP_DEFAULT_FLOW
58 * @details A flow defines a set of free queues (pktlib heap) for h/w to use to get free packet descriptor(s) and buffer(s) to use when receiving a packet
59 */
60 typedef struct NETCP_CFG_FLOW_Tag
61 {
62 int flowid; /**< flow id*/
63 int dma_engine; /**< dma engine (QMSS, NETCP)*/
64 } NETCP_CFG_FLOW_T;
67 /**
68 * @ingroup cfg_structures
69 * @brief NETAPI configuration information
70 *
71 * @details The parameters in this structure are used to configure NETAPI.
72 */
73 typedef struct NETAPI_CFG_Tag
74 {
75 int def_mem_size; /**< Bytes of CMA memory we have allocated */
76 int def_flow_pkt_rx_offset; /**< Offset in pkt buffer for hw to start RX */
77 int def_max_descriptors; /**< Number of descriptors in system (must be power of 2), 2^14 max */
78 int def_tot_descriptors_for_us; /**< Number of descriptors to create in our region (must be power of 2)*/
79 int def_heap_n_descriptors; /**< Number of descriptor plus buffers in default heap*/
80 int def_heap_n_zdescriptors; /**< Number of zero len descriptors in defaut heap*/
81 int def_heap_buf_size; /**< Size of buffers in default heap, max amount of area for packet data */
82 int def_heap_tailroom_size; /**< Size of tailroom in reserve */
83 int def_heap_extra_size; /**< Size of extra space at end of buffer */
84 } NETAPI_CFG_T;
86 /* @note:
87 each buffer will be allocated: def_heap_buf_size+def_heap_extra_size bytes
88 each descriptor attached to these buffers will have rigBufferLen of:
89 def_heap_buf_size.
90 for default RX flow, for rx packet, the bufptr will be def_flow_pkt_rx_offset.
91 for detault RX flow, threshold (ie max # of bytes in buffer) will be:
92 def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
95 RX Packet from NetCP
97 Headroom [Application] Packet [HW] Tailroom [Application] Extra Space [Application]
98 <-----------------------><--------------------------><------------------------><----------------------->
100 Cppi_HostDesc->origBufferLen
101 <----------------------------------------------------------------------------->
102 Cppi_HostDesc->origBuffPtr
103 |
104 \/
105 |------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
106 | def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size | Extra Size |
107 ^
108 |
109 Cppi_HostDesc->buffPtr
110 */
113 /**
114 * @ingroup cfg_constants
115 * @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.
116 */
117 typedef void * NETCP_CFG_FLOW_HANDLE_T;
119 /**
120 * @ingroup cfg_constants
121 * @def NETCP_DEFAULT_FLOW
122 * @brief This defines the default FLOW for NETCP to use.
123 * The default flow uses the default pktlib heap created by netapi_init; i.e. NETCP will allocate descriptors and buffers for received packets from this heap.
124 */
125 #define NETCP_DEFAULT_FLOW (NETCP_CFG_FLOW_HANDLE_T*) NULL
128 /**
129 * @ingroup cfg_constants
130 * @brief Handle to a NETCP route.
131 * @details Application to use this handle to identify a NETCP route. A NETCP route defines the pktio channel for packets received by NETCP
132 * and the flow to use.
133 */
134 typedef void * NETCP_CFG_ROUTE_HANDLE_T;
136 /**
137 * @def NETCP_DEFAULT_ROUTE
138 * This defines the NETCP default route. This route has NETCP send received packets to the default NETCP
139 * pktio channel using descriptors and buffers from the default flow. The default route is created by netapi_init
140 */
141 #define NETCP_DEFAULT_ROUTE (NETCP_CFG_ROUTE_HANDLE_T*) NULL
144 /**
145 * @ingroup cfg_structures
146 * @brief NETCP application defined route information.
147 * @details This structure is used to define a packet receive route. A route consists of a flow where to get free descriptors and buffers to hold the packet, and a destination queue where to place the packet.
148 *
149 */
150 typedef struct NETCP_CFG_ROUTE_Tag
151 {
152 NETCP_CFG_FLOW_T * p_flow; /**< NULL or NETCP_DEFAULT_FLOW for default flow, @ref NETCP_CFG_FLOW_T */
153 PKTIO_HANDLE_T * p_dest_q; /**<NULL for default destination queue */
154 } NETCP_CFG_ROUTE_T;
156 /**
157 * @ingroup cfg_constants
158 * @def NETCP_CFG_ACTION_DISCARD
159 * This defines the NETCP action to discard packet.
160 */
161 #define NETCP_CFG_ACTION_DISCARD NWAL_MATCH_ACTION_DISCARD
162 /**
163 * @ingroup cfg_constants
164 * @def NETCP_CFG_ACTION_CONTINUE
165 * This defines the NETCP action to pass packet ono the next classifier
166 */
167 #define NETCP_CFG_ACTION_CONTINUE NWAL_MATCH_ACTION_CONTINUE_NEXT_ROUTE
168 /**
169 * @ingroup cfg_constants
170 * @def NETCP_CFG_ACTION_TO_SW
171 * This defines the NETCP action to pass packet to User space application
172 */
173 #define NETCP_CFG_ACTION_TO_SW NWAL_MATCH_ACTION_HOST
175 /**
176 * @ingroup cfg_constants
177 * @def NETCP_CFG_ALL_EXCEPTIONS
178 * This defines NETCP configuration for all Exepction Packets.
179 */
180 #define NETCP_CFG_ALL_EXCEPTIONS 0xff
185 /**
186 * @ingroup cfg_constants
187 * @brief Handle to NETCP VLAN configuration (FUTURE).
188 * @details Application to use this handle to identify a VLAN configuration.
189 */
190 typedef void * NETCP_CFG_VLAN_T;
192 /**
193 * @ingroup cfg_constants
194 * @brief AppID for packets matching a MAC interface rule
195 */
196 typedef uint32_t NETCP_CFG_MACIF_T;
198 /**
199 * @ingroup cfg_constants
200 * @brief AppID for packets matching an IP interface rule
201 */
202 typedef uint32_t NETCP_CFG_IP_T;
204 /**
205 * @ingroup cfg_constants
206 * @brief This define is used to identify the application id associated with a created SA (IPSEC security association) rule
207 */
208 typedef uint32_t NETCP_CFG_SA_T;
211 /**
212 * @ingroup cfg_constants
213 * @brief AppId for packets matching an NETCP IPSEC policy rule
214 */
215 typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
219 /**
220 * @ingroup cfg_constants
221 * @brief AppID for packets being classified as type exception.
222 */
223 typedef uint32_t NETCP_CFG_EXCEPTION_PKT_T;
225 /**
226 * @ingroup cfg_constants
227 *@brief This define is to be used in AddIp, AddClassifier, addSA, etc. to indicate that the rule can be bound to any MAC address.
228 */
229 #define NETCP_CFG_NO_INTERFACE 0xff
233 /**
234 * @note APPIDs are present in RX packet meta data and tell "how far" the packet got
235 * through the classification rules of NETCP.
236 * APPID is 32 bits:
237 * bits 31-24 = NETAPI_NETCP_MATCH_STAGE
238 * bits 23-8 = NETAPI_NETCP_MATCH_ID identifier
239 * bits 7-0 = NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE logical mac interface
240 */
242 #define NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT 0
243 #define NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK 0xFF
245 #define NETAPI_NETCP_MATCH_ID_SHIFT 8
246 #define NETAPI_NETCP_MATCH_ID_MASK 0xFFFF
248 #define NETAPI_NETCP_MATCH_STAGE_SHIFT 24
249 #define NETAPI_NETCP_MATCH_STAGE_MASK 0xFF
251 #define netapi_cfgGetMatchStage(appid) (((appid) >> NETAPI_NETCP_MATCH_STAGE_SHIFT) & NETAPI_NETCP_MATCH_STAGE_MASK)
252 #define netapi_cfgGetMatchId(appid) (((appid) >> NETAPI_NETCP_MATCH_ID_SHIFT) & NETAPI_NETCP_MATCH_ID_MASK)
253 #define netapi_cfgGetMatchLogicalMacIface(appid) (((appid) >> NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT) & \
254 NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK)
257 /**
258 * @ingroup cfg_constants
259 * @def NETAPI_NETCP_MATCH_GENERIC_MAC
260 * This define is used for an APPID that indicates that a packet matched a MAC entry.
261 * Logical MAC interface location:
262 * Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and
263 * NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
264 * Packet did not match any other rule.
265 */
266 #define NETAPI_NETCP_MATCH_GENERIC_MAC 0x10000000
268 /**
269 * @ingroup cfg_constants
270 * @def NETAPI_NETCP_MATCH_GENERIC_IP
271 * This define is used for an APPID that indicates that a packet matched a MAC entry.
272 * Logical MAC interface location:
273 * Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and
274 * NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
275 * IP rule number for this interface location:
276 * Refer to NETAPI_NETCP_MATCH_ID_SHIFT and
277 * NETAPI_NETCP_MATCH_ID_MASK.
278 * Packet also matched a generic IP rule attached to that interface.
279 * Packet did not match any other rule.
280 */
281 #define NETAPI_NETCP_MATCH_GENERIC_IP 0x20000000
283 /**
284 * @ingroup cfg_constants
285 * @def NETAPI_NETCP_MATCH_CLASS
286 * This define is used for an APPID that indicates that a packet matched a MAC entry.
287 * Logical MAC interface location:
288 * Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and
289 * NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
290 * Classifer ID location:
291 * Refer to NETAPI_NETCP_MATCH_ID_SHIFT and
292 * NETAPI_NETCP_MATCH_ID_MASK.
293 * Packet also matched a generic IP rule attached to
294 * that interface OR a general IP rule added as part of the classifier or it matched a combination
295 * of ISPEC SA rule and a policy check. In addition, packet matched a L4 port rule that was added
296 * as part of a classifer. Packet did not match any other rule.
297 */
298 #define NETAPI_NETCP_MATCH_CLASS 0x80000000
300 /**
301 * @ingroup cfg_constants
302 * @def NETAPI_NETCP_MATCH_CLASS_L3
303 * This define is used for an APPID that indicates that a packet matched a MAC entry.
304 * Logical MAC interface location:
305 * Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and
306 * NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
307 * Packet also matched a general IP rule added as part
308 * of a classifier. But it not match a L4 port or any other rule.
309 * We cannot determine what classifer partially matched so Bytes 3-2 are not applicable
310 */
311 #define NETAPI_NETCP_MATCH_CLASS_L3 0x40000000
313 /**
314 * @ingroup cfg_constants
315 * @def NETAPI_NETCP_MATCH_IPSEC
316 * This define is used for an APPID that indicates that a packet matched a MAC entry.
317 * Logical MAC interface location:
318 * Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and
319 * NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
320 * SA ID location:
321 * Refer to NETAPI_NETCP_MATCH_ID_SHIFT and
322 * NETAPI_NETCP_MATCH_ID_MASK.
323 * Packet also matched an IPSEC SA rule (matched proto, destination ip and SPI).
324 * Packet did not match any other rule (so may have failed a policy check)
325 */
326 #define NETAPI_NETCP_MATCH_IPSEC 0x01000000
329 /**
330 * @ingroup cfg_constants
331 * @def NETAPI_NETCP_MATCH_IPSEC_POLICY
332 * This define is used for an APPID that indicates that a packet matched a MAC entry
333 * Logical MAC interface location:
334 * Refer to NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_SHIFT and
335 * NETAPI_NETCP_MATCH_LOGICAL_MAC_IFACE_MASK.
336 * Packet also matched an IPSEC SA rule (matched proto,
337 * dest ip and SPI). Packet also matched a POLICY RULE (this is a check of the inner IP).
338 * IPSEC RX Policy ID location:
339 * Refer to NETAPI_NETCP_MATCH_ID_SHIFT and
340 * NETAPI_NETCP_MATCH_ID_MASK.
341 * Packet did not match any other rule
342 */
343 #define NETAPI_NETCP_MATCH_IPSEC_POLICY 0x02000000 //lower byte==interface, Or' in SA id (16 bits)
345 /**
346 * @ingroup cfg_constants
347 * @def NETAPI_NETCP_CFG_MATCH_EXCEPTION
348 * This define is used for an APPID that indicates that a packet is of type exception.
349 * Actual exception id is in byte 0 of APPID.
350 */
351 #define NETAPI_NETCP_CFG_MATCH_EXCEPTION 0x08000000
355 /**
356 * @ingroup cfg_structures
357 * @brief NETCP flow configuration information.
358 * @details This structure is used to define key parameters for the receive flow to be created.
359 * These include the flow index to use (or can be left un-specified), the dma_index
360 * (specifying out of which CPPI DMA engine the flow should be allocated),
361 * the receive offset (the byte offset into each buffer where received data should be placed),
362 * and the drop policy for the DMA channel to use if there is no free buffer available (drop or block)
363 *
364 */
365 typedef struct NETCP_CFG_FLOW_CONFIG_Tag
366 {
367 int flow_index; /**< flow index to use or NETAPI_NETCP_FLOW_INDEX_ANY */
368 /**
369 * @def NETAPI_NETCP_FLOW_INDEX_ANY
370 * @ingroup cfg_constants
371 * This define is used to let NETAPI pick the flow index to use(for flow_index field)
372 */
373 #define NETAPI_NETCP_FLOW_INDEX_ANY CPPI_PARAM_NOT_SPECIFIED
375 int dma_index; /**< allocate flow out of which DMA */
376 /**
377 * @def NETAPI_DMA_INFRASTRUCTURE
378 * @ingroup cfg_constants
379 * This define is used specify a flow in the QMSS CPPI DMA (for dma_index field)
380 */
381 #define NETAPI_DMA_INFRASTRUCTURE 0
382 /**
383 * @def NETAPI_DMA_NETCP
384 * @ingroup cfg_constants
385 * This define us usee specify a flow in the NETCP CPPI DMA (for dma_index field)
386 */
387 #define NETAPI_DMA_NETCP 1
389 int recv_offset; /**< start of packet offset */
391 int block; /**< TRUE => DMA will wait for free descriptor if heap(s) are empty.
392 FALSE => DMA will discard */
393 /**
394 * @def NETAPI_FLOW_DROP
395 * @ingroup cfg_constants
396 * This define is used to indicate that the flow should institute a Block policy.
397 * This means that the DMA should wait for a free descriptor/buffer to come available if
398 * the free poll is empty (for the block field)
399 */
400 #define NETAPI_FLOW_BLOCK 1
401 /**
402 * @def NETAPI_FLOW_DROP
403 * @ingroup cfg_constants
404 * This define us used to indicate that the flow should institute a Drop policy.
405 * This means that the DMA should NOT wait for a free descriptor/buffer to come available
406 * if the free poll is empty. The transfer will be aborted and the data will dropped (for block field)
407 */
408 #define NETAPI_FLOW_DROP 0
410 PKTIO_HANDLE_T * p_dest_q; /**<destination queue for this flow (may be overwrritten by source DMA) */
411 } NETCP_CFG_FLOW_CONFIG_T;
418 /**
419 * @ingroup cfg_functions
420 * @brief netapi_netcpCfgAddFlow API to add a flow
421 *
422 * @details This api is used to add a flow
423 * @param[in] h NETAPI instance handle, @ref NETAPI_T
424 * @param[in] n number of Pktlib_HeapHandle
425 * @param[in] handles[] Handles to Pktlib_HeapHandle
426 * @param[in] sizes[] must be <= heap corresponding heap size-recv_offset-any desired tail room
427 * @param[in] p_cfg @ref NETCP_CFG_FLOW_CONFIG_T
428 * @param[out] err pointer to error return
429 * @retval NETCP flow handle, @ref NETCP_CFG_FLOW_HANDLE_T
430 * @pre @ref netapi_init
431 */
432 NETCP_CFG_FLOW_HANDLE_T netapi_netcpCfgAddFlow(NETAPI_T h,
433 int n,
434 Pktlib_HeapHandle handles[],
435 int sizes[],
436 NETCP_CFG_FLOW_CONFIG_T * p_cfg,
437 int * err );
439 /**
440 * @ingroup cfg_functions
441 * @brief netapi_netcpCfgDelFlow API to delete a flow
442 *
443 * @details This api is used to delete a flow.
444 * @param[in] h NETAPI instance handle, @ref NETAPI_T
445 * @param[in] p handle to NETCP flow
446 * @param[out] err pointer to error return
447 * @retval none
448 * @pre @ref netapi_init, netapi_netcpCfgAddFlow
449 */
450 void netapi_netcpCfgDelFlow(NETAPI_T h ,
451 NETCP_CFG_FLOW_HANDLE_T p ,
452 int * err);
454 /**
455 * @ingroup cfg_functions
456 * @brief API attaches an IP address and qualifier to a MAC interface
457 *
458 * @details This api is used to add an IP address to a MAC interface along
459 * with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default
460 * may be specified to indicate where to send packets matching the MAC interface MAC address, the
461 * supplied IP address and any qualifier. This API adds a rule to the NETCP level 1 lookup tables
462 * Packets arriving that match this rule are identified in meta data with Appid= NETAPI_NETCP_MATCH_GENERIC_IP
463 * Note: An IP address must be attached to enable NETCP receive Checksum offload feature
464 * @param[in] h NETAPI instance handle, @ref NETAPI_T
465 * @param[in] iface_no interface number (0,1,..)
466 * @param[in] ipType type of IP address (V4 for V6)
467 * @param[in] ip_addr ip_address
468 * @param[in] ip_qualifiers ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
469 * diffserv category for example.
470 * @param[in] route handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
471 * @param[in] user_data Optional: pointer to user provided data associated with IP
472 * @param[out] err pointer to error return
473 * @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
474 * @pre @ref netapi_init
475 */
476 NETCP_CFG_IP_T netapi_netcpCfgAddIp(NETAPI_T h,
477 int iface_no,
478 nwal_IpType ipType,
479 nwalIpAddr_t* ip_addr,
480 nwalIpOpt_t* ip_qualifiers,
481 NETCP_CFG_ROUTE_HANDLE_T route,
482 void* user_data,
483 int* err);
485 /**
486 * @ingroup cfg_functions
487 * @brief netapi_netcpCfgDelIp API to delete IP interface
488 *
489 * @details This api is used to delete an IP interface
490 * @param[in] h NETAPI instance handle, @ref NETAPI_T
491 * @param[in] iface_no interface number (0,1,..)
492 * @param[in] ipType type of IP address (V4 for V6)
493 * @param[in] ip_addr ip_address
494 * @param[in] ip_qualifiers ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
495 * diffserv category for example.
496 * @param[in] ip_rule_id @ref NETCP_CFG_IP_T
497 * @param[out] err pointer to error return
498 * @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
499 * @pre @ref netapi_init , @ref netapi_netcpCfgAddIp
500 */
501 void netapi_netcpCfgDelIp(NETAPI_T h,
502 int iface_no,
503 nwal_IpType ipType,
504 nwalIpAddr_t* ip_addr,
505 nwalIpOpt_t* ip_qualifiers,
506 NETCP_CFG_IP_T ip_rule_id,
507 int* err);
509 /**
510 * @ingroup cfg_functions
511 * @brief netapi_netcpCfgCreateMacInterface API to create a MAC interface
512 *
513 * @details This api is used to create a MAC interface.
514 * Once it is created, the MAC interface can be used to receive packets. The API
515 * adds a rule to the NETCP 1st level lookup tables to route all packets with destination
516 * MAC matching supplied argument and not matching any other lookup entry (see @ref netapi_netcpCfgAddIp) to
517 * the supplied route, @ref NETCP_CFG_ROUTE_T, (or default route).
518 * Packets arriving that match this rule are identified in meta data with Appid= NETAPI_NETCP_MATCH_GENERIC_MAC
519 * Note: The internal SOC switch (if operating in full swithc mode) may need to be "taught" that this mac
520 * address is present by transmitting a packet with destination mac = this interface mac address.
521 * @param[in] h NETAPI instance handle, @ref NETAPI_T
522 * @param[in] p_mac pointer to 6 byte MAC address for interface
523 * @param[in] iface_no interface number (0,1,..)
524 * @param[in] switch_port (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported currenly]
525 * @param[in] route handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
526 * @param[in] vlan [future[ vlan configuration . Set to NULL, @ref NETCP_CFG_VLAN_T
527 * @param[in] state [future] interface state (0=down, 1= up)
528 * @param[out] err pointer to error return
529 * @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
530 * @pre @ref netapi_init
531 */
532 NETCP_CFG_MACIF_T netapi_netcpCfgCreateMacInterface(NETAPI_T h,
533 uint8_t* p_mac,
534 int iface_no,
535 int switch_port,
536 NETCP_CFG_ROUTE_HANDLE_T route,
537 NETCP_CFG_VLAN_T vlan,
538 int state,
539 int * err);
541 /**
542 * @ingroup cfg_functions
543 * @brief netapi_netcpCfgDelMac API to delete MAC interface
544 *
545 * @details This api is used to delete a MAC interface
546 * @param[in] h NETAPI instance handle, @ref NETAPI_T
547 * @param[in] iface_no interface number (0,1,..)
548 * @param[out] err pointer to error return
549 * @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
550 * @pre @ref netapi_init , @ref netapi_netcpCfgCreateMacInterface
551 */
552 void netapi_netcpCfgDelMac(NETAPI_T h,
553 int iface_no,
554 int* err);
557 /**
558 * @brief This defines handle to installed classifier returned by API. Pkts matching this classifier will have meta data with this tag.
559 * Also used to delete classifier
560 */
561 typedef uint32_t NETCP_CFG_CLASS_T;
564 /**
565 * @ingroup cfg_structures
566 * @brief NETAPI Class L4 Configuration
567 *
568 * @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)
569 */
570 typedef struct NETCP_CFG_CLASS_L4_Tag
571 {
572 int iface; /**< Indicates which MAC interface packet should be received on*/
573 NETCP_CFG_IP_T ip; /**< IP rule to match: see @ref NETCP_CFG_IP_T */
574 nwal_appProtoType_t proto; /**< L4 proto (-1 for don't care)*/
575 nwalAppProto_t appProto; /**< L4 Ports or equivalent */
577 } NETCP_CFG_CLASS_L4_T;
580 /**
581 * @ingroup cfg_structures
582 * @brief NETAPI Classifier L4 plus IPSEC policy configuration
583 *
584 * @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.
585 */
586 //classifier L4 + policy (L2, L3 (outer), tunnel, L3 (inner) implied by policy
587 typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
588 {
589 int iface; /**< Indicates which MAC interface packet should be received from */
590 NETCP_CFG_IPSEC_POLICY_T ip_policy; /**< IPSEC policy configuration. see @ref NETCP_CFG_IPSEC_POLICY_T */
591 nwal_appProtoType_t proto; /**< L4 proto (-1 for don't care)*/
592 nwalAppProto_t appProto; /**< L4 Ports or equivalent */
594 } NETCP_CFG_CLASS_L4_IPSEC_T;
598 /**
599 * @ingroup cfg_structures
600 * @brief NETAPI Classifier L4/L3 configuration
601 *
602 * @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.
603 */
604 typedef struct NETCP_CFG_CLASS_L3_L4_Tag
605 {
606 int iface; /**< Indicates which MAC interface packet is from */
607 nwal_IpType ipType; /**< IP address type, IPV4 or IPV6 */
608 nwalIpAddr_t* ip_addr; /**< IP address to match */
609 nwalIpOpt_t* ip_qualifiers; /**< IP address qualifiers */
610 NETCP_CFG_ROUTE_HANDLE_T p_fail_route; /**< What to do if L3 matches but L4 fails AND L3 is a
611 new rule.(if exisitng rule, then existing fail
612 route will be used). */
613 nwal_appProtoType_t proto; /**< L4 proto (-1 for don't care)*/
614 nwalAppProto_t appProto; /**< Ports or equivalent */
615 } NETCP_CFG_CLASS_L3_L4_T;
617 /**
618 * @ingroup cfg_structures
619 * @brief NETAPI Classifier configuration
620 *
621 * @details This structure contains the NETAPI classifer configuration. This is a union of the different classifier types above
622 */
623 typedef struct NETCP_CFG_CLASSIFIER_Tag
624 {
626 /**
627 * Classifer type which can be set to one of the following defines:
628 * <br>
629 * @ref NETCP_CFG_CLASS_TYPE_L4 , @ref NETCP_CFG_CLASS_TYPE_L3_L4, _
630 */
631 int classType;
633 /**
634 * @def NETCP_CFG_CLASS_TYPE_L4
635 * @ingroup cfg_constants
636 * 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
637 */
638 #define NETCP_CFG_CLASS_TYPE_L4 0
640 /**
641 * @def NETCP_CFG_CLASS_TYPE_L3_L4
642 * @ingroup cfg_constants
643 * 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.
644 */
645 #define NETCP_CFG_CLASS_TYPE_L3_L4 1
647 union
648 {
649 NETCP_CFG_CLASS_L3_L4_T c_l3_l4; /**< @ref NETCP_CFG_CLASS_L3_L4_T */
650 NETCP_CFG_CLASS_L4_T c_l4; /**< @ref NETCP_CFG_CLASS_L4_T */
651 NETCP_CFG_CLASS_L4_IPSEC_T c_l4_ipsec; /**< @ref NETCP_CFG_CLASS_L4_IPSEC_T */
652 } u; /**< union for classifier type configuration structure */
653 } NETCP_CFG_CLASSIFIER_T;
657 /**
658 * @ingroup cfg_functions
659 * @brief netapi_netcpCfgAddClass API to attach a classifier rule to NETCP.
660 * This can be used to route a particular packet flow to a specific PKTIO channel
661 *
662 * @details This api can be used to route a particular packet flow to a particular PktIO channel, using a specific
663 * pktLib heap, and/or have NetCP attach a tag (classifier id) to the incoming packet.
664 * @param[in] h NETAPI instance handle, @ref NETAPI_T
665 * @param[in] p_class definition of the classifier
666 * @param[in] p_route handle to NETCP route.
667 * @param[in] action what to do with packet: one of NETCP_CFG_ACTION_TO_SW, DISCARD or CONTINUE
668 * @param[in] user_data Optional: pointer to user provided data associated with SA
669 * @param[out] err pointer to error return
670 * @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
671 * @pre @ref netapi_init
672 */NETCP_CFG_CLASS_T netapi_netcpCfgAddClass(NETAPI_T h,
673 NETCP_CFG_CLASSIFIER_T* p_class,
674 NETCP_CFG_ROUTE_HANDLE_T p_route,
675 int action,
676 void* user_data,
677 int* err);
681 /**
682 * @ingroup cfg_functions
683 * @brief netapi_netcpCfgDelClass API to delete a preconfigured classifier
684 *
685 * @details This API can be used to delete a preconfigured classifier
686 * @param[in] h NETAPI instance handle, @ref NETAPI_T
687 * @param[in] classId
688 * @param[out] err pointer to error return
689 * @retval none
690 * @pre @ref netapi_init, @ref netapi_netcpCfgAddClass
691 */
692 void netapi_netcpCfgDelClass(NETAPI_T h,
693 NETCP_CFG_CLASS_T classId,
694 int* err);
697 /**
698 * @ingroup netapi_cb_functions
699 * @brief NETCP_CFG_STATS_CB Callback function that is used to return statistics from NETCP
700 *
701 * @details The application provides a callback function that NETAPI uses to report statistics.
702 * The request for stats is generated from the @ref netapi_netcpCfgReqStats API.
703 * Note: to receive this stats callback, the @ref netapi_netcpPoll function must be called
704 * @param[in] h NETAPI instance handle, @ref NETAPI_T
705 * @param[out] pPaStats the PA (NETCP packet accelerator subsystem) statistics block
706 * @retval none
707 * @pre @ref netapi_init , @ref netapi_netcpCfgReqStats, @ref netapi_netcpPoll
708 */
709 typedef void (*NETCP_CFG_STATS_CB)(NETAPI_T h,
710 paSysStats_t* pPaStats);
712 /**
713 * @ingroup cfg_functions
714 * @brief netapi_netcpCfgReqStats API to request statistics from NETCP
715 *
716 * @details This api is used to request a statistics from NETCP. This will generate a stats request
717 * command to NETCP. Sometime later, the statistics result will arrive and will be passed to
718 * the caller via the asynchronus callback @ref NETCP_CFG_STATS_CB that is registered in this call.
719 * Note: to receive the stats callback, the @ref netapi_netcpPoll funcition must be called
720 * @param[in] h NETAPI instance handle, @ref NETAPI_T
721 * @param[in] cb the callback function to invoke with the resulting statistics block, @ref NETCP_CFG_STATS_CB
722 * @param[in] doClear clear the stats in NETCP after the report (0=no, 1=yes)
723 * @param[out] err pointer to error return
724 * @retval none
725 * @pre @ref netapi_init
726 */
727 void netapi_netcpCfgReqStats(NETAPI_T h,
728 NETCP_CFG_STATS_CB cb,
729 int doClear,
730 int* err);
733 /**
734 * @ingroup cfg_functions
735 * @brief netapi_netcpCfgExceptions API to configure NETCP with global rules for exception packet handling
736 *
737 * @details This api is used to configure NETCP with global rules of how to handle exception packets specified by exception_id.
738 * @param[in] h NETAPI instance handle, @ref NETAPI_T
739 * @param[in] exception_id id of the exception packet, refer to pa.h,.pa_EROUTE_XXX for list of exception packet id's
740 * @param[in] p_route handle to NETCP route.
741 * @param[in] action, action for NETCP to take upon classifying packet as type exception, refer to nwal. nwal_matchAction_t
742 * @retval returns app_id, @ref NETCP_CFG_EXCEPTION_PKT_T
743 * @pre @ref netapi_init
744 */
745 NETCP_CFG_EXCEPTION_PKT_T netapi_netcpCfgExceptions(NETAPI_T h,
746 int exception_id ,
747 nwal_matchAction_t action,
748 NETCP_CFG_ROUTE_HANDLE_T p_route);
751 #endif