#ifndef _PA_FC_H #define _PA_FC_H #ifdef __cplusplus extern "C" { #endif /* System level header files */ #include #include #include /* ============================================================= */ /** * @file pa_fc.h * * path ti/drv/pa/pa_fc.h * * @brief Packet Accelerator (PA) sub-system LLD Flow Cache related API and Data Definitions * * ============================================================================ * Copyright (c) Texas Instruments Incorporated 2013 * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the * distribution. * * Neither the name of Texas Instruments Incorporated nor the names of * its contributors may be used to endorse or promote products derived * from this software without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */ /** * @page appendix4 Flow Cache * * The PASS Flow Cache operation consits of the following three sub-operations: * - Flow Cache Classification: Classify up to 256 established egress flows based on * the inner IP and L4 parameters. * - Egress Flow Operation: Perform up to 4-level packet modification such as IP mangling, * IPSEC framing and encryption, L2 framing and etc per packet * modification records. * - Ingress Packet Forwarding: Route the ingress packets to the Egress processing unit * as one of the classification routing options. * * The flow cache operation can be used to help glue the ingress path to the egress path to * establish a fully automated processing chain without host intervention. It may be only * applied to egress packets from the host to establish fully-offloaded egress chain operation * with or without flow cache classification. * * The flow cache classification module resides at PASS Egress0 clsuter and it supports 256 * LUT1 entries, each entry consists of any combination of IP and UDP/TCP parameters as defined * at @ref paFcInfo_t. Each flow cache entry is also assocaited with a pre-determined egress flow * where the egress packets will undertake up to 4-level of packet modification defined by * the egress flow packet modification records, which are described at the next section. The API * @ref Pa_addFc() and @ref Pa_delFcHandle are used to add and delete the Flow Cache entries respectively. * * Each egress flow consists of up to four packet modification stages where the packet can undergo * transformations in the egress path, before it is sent out from PASS. The four packet modification * stages are * @li Inner L3/L4 Processing * @li Outer L3/IPSEC Processing * @li IPSEC AH/ NAT Processing * @li L2 Processing * * The detailed operation of each packet modification stage is defined at its corresponding egress flow * record defintion sections(@ref paEfRecLevel1_t, @ref paEfRecLevel2_t, @ref paEfRecLevel3_t and * @ref paEfRecLevel4_t) The API @ref Pa_configEflowRecords is used to add/delete single or multiple * packet modification records. * * The ingress traffic may be routed to the egress path at each of the following four classification stages: * - L2 classification: Only L2 processing is allowed at the egress path to support application * such as MAC routing * - Outer IP classification: Support outer L3/IPSEC and L2 processing only without Flow Cache classification * Support all four egress stages with Flow Cache classification * - Inner IP classification: Support all four egress stages with and without Flow Cache classification * - L4 classification: Support all four egress stages with and without Flow Cache classification * * The advanced routing information data structure @ref paRouteInfo2_t with flow cache operation * data structure @ref paEfOpInfo_t are used to define flow cache route. */ /** * @defgroup paEflowErouteTypes PA Egress Flow Exception Route Types * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Exception Route Types * * @brief These values are used to define exception route conditions in egress path. * * @details The Egress Flow exception route defines the global routing information when the exception * condition such as Flow Cache lookup failure, packet parsing failure, TCP control detection * and etc. Multiple exception routes can be configured through @ref Pa_configEflowExceptionRoute. * The PASS will drop all exception route packets by default until the corresponding exception * route is configured. */ /* @{ */ /** * * @def pa_EFLOW_EROUTE_FC_FAIL * packet failed to match in Flow Cache (LUT1) table */ #define pa_EFLOW_EROUTE_FC_FAIL 0 /** * @def pa_EFLOW_EROUTE_PARSE_FAIL * packet failed to parse */ #define pa_EFLOW_EROUTE_PARSE_FAIL 1 /** * @def pa_EFLOW_EROUTE_IP_FRAG * IP fragmented packet */ #define pa_EFLOW_EROUTE_IP_FRAG 2 /** * @def pa_EFLOW_EROUTE_IPV6_OPT_FAIL * Packet failed due to unsupported IPV6 option header */ #define pa_EFLOW_EROUTE_IPV6_OPT_FAIL 3 /** * @def pa_EFLOW_EROUTE_IP_OPTIONS * IP packet with IPv4 options or IPv6 extension headers */ #define pa_EFLOW_EROUTE_IP_OPTIONS 4 /** * @def pa_EFLOW_EROUTE_IP_EXPIRE * IP packet with TTL expired or Hop Limitis reached */ #define pa_EFLOW_EROUTE_IP_EXPIRE 5 /** * @def pa_EFLOW_EROUTE_TCP_CTRL * TCP Control packets where one or more control bits * (SYN, FIN, and RST) are set */ #define pa_EFLOW_EROUTE_TCP_CTRL 6 /** * @def pa_EFLOW_EROUTE_INVALID_REC * Invalid Egree Flow Records */ #define pa_EFLOW_EROUTE_INVALID_REC 7 /** * @def pa_EFLOW_EROUTE_SYSTEM_FAIL * Sub-system detected internal error */ #define pa_EFLOW_EROUTE_SYSTEM_FAIL 10 /** * @def pa_EFLOW_EROUTE_MAX * The maximum number of global route types */ #define pa_EFLOW_EROUTE_MAX 11 /* @} */ /** @} */ /** * @ingroup palld_api_functions * @brief Pa_configEflowExceptionRoute configures the routing of packets based on an exception condition such as * no match, parsing failure, TCP control packet etc in the egress direction (PASS Gen2 only) * * @details This function is used to configure the sub-system to route packets that satisfy an exception * rule or condition (see @ref paEflowErouteTypes) in the egress direction. For example, * - failure to flow cache table match * - parsing error i.e. the sub-system is not able to continue parsing the packets * - TCP contrl packet * - system failure * * From one to @ref pa_EFLOW_EROUTE_MAX routes can be specified through a single call to this * function. Parameter nRoute is used to specify how many routes are contained in the * routeTypes and eRoutes arrays. A value of 0 nRoutes results in no action by the function. * * By default when each exception type is detected the packet is discarded silently. Once the * route is changed through a call to this function it remains in the new state until the * function is called again to explicitly change that route. The only way to revert back * to the default of silent discard is to call this function again. * * On return the command buffer (cmd) contains a formatted command for the sub-system. * The destination for the command is provided in cmdDest. The module user must send the * formatted command to the sub-system. The sub-system will generate a reply and this reply * must be sent back to this module through the API @ref Pa_forwardResult. * * @param[in] iHandle The driver instance handle * @param[in] nRoute The number of exception routes specified * @param[in] routeTypes Array of exception routing types (@ref paEflowErouteTypes) * @param[in] eRoutes Array of exception packet routing configuration * @param[out] cmd Buffer where the sub-system command is created * @param[in] cmdSize The size of the passCmd buffer * @param[in] reply Where the response to the PASS command is routed * @param[out] cmdDest Value (@ref cmdTxDest) * @retval Value (@ref ReturnValues) * @pre A driver instance must be created and tables initialized * * @note: This API is not supported at the first generation PASS */ paReturn_t Pa_configEflowExceptionRoute (Pa_Handle iHandle, int nRoute, int *routeTypes, paRouteInfo_t *eRoutes, paCmd_t cmd, uint16_t *cmdSize, paCmdReply_t *reply, int *cmdDest); /** * @defgroup paEflowRecTypes PA Egress Flow Record types * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Record types * * @brief These values are used to define the modification record types in the egress flow operation * */ /* @{ */ /** * * @def pa_EFLOW_REC_TYPE_LVL1 * Level1: Inner L3/L4 Processing */ #define pa_EFLOW_REC_TYPE_LVL1 1 /** * * @def pa_EFLOW_REC_TYPE_LVL2 * Level2: Outer L3/IPSEC Processing */ #define pa_EFLOW_REC_TYPE_LVL2 2 /** * * @def pa_EFLOW_REC_TYPE_LVL3 * Level3: IPSEC AH/IPSEC ESP NAT-T Processing */ #define pa_EFLOW_REC_TYPE_LVL3 3 /** * * @def pa_EFLOW_REC_TYPE_LVL4 * Level1: L2 Processing */ #define pa_EFLOW_REC_TYPE_LVL4 4 /* @} */ /** @} */ /** * @defgroup paEfLvl1RecordValidBits PA Egress Flow Level One Record Valid Bit Definitions * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Level One Record Valid Bit Definitions * * Bitmap definition of the validBitMap in @ref paEfRecLevel1_t. */ /*@{*/ /** * @def pa_EF_LVL1_RECORD_VALID_CTRL_FLAGS * - Level One record control flags is present */ #define pa_EF_LVL1_RECORD_VALID_CTRL_FLAGS 0x0001 /** * @def pa_EF_LVL1_RECORD_VALID_IP_SRC * - Source IP address in packet should be replaced with the one in record */ #define pa_EF_LVL1_RECORD_VALID_IP_SRC 0x0002 /** * @def pa_EF_LVL1_RECORD_VALID_IP_DST * - Destination IP address in packet should be replaced with the one in record */ #define pa_EF_LVL1_RECORD_VALID_IP_DST 0x0004 /** * @def pa_EF_LVL1_RECORD_VALID_FLOW_LABEL * - IPv6 flow label in packet should be replaced with the one in record */ #define pa_EF_LVL1_RECORD_VALID_FLOW_LABEL 0x0008 /** * @def pa_EF_LVL1_RECORD_VALID_TOS_CLASS * - IPv4 type of service or IPv6 traffic class in packet should be replaced with the one in record */ #define pa_EF_LVL1_RECORD_VALID_TOS_CLASS 0x0010 /** * @def pa_EF_LVL1_RECORD_VALID_IP_MTU * Inner IP MTU is specified, perform Inner IP fragmentation is necessary */ #define pa_EF_LVL1_RECORD_VALID_IP_MTU 0x0020 /** * @def pa_EF_LVL1_RECORD_VALID_SRC_PORT * TCP/UDP source port in packet should be replaced with the one in record */ #define pa_EF_LVL1_RECORD_VALID_SRC_PORT 0x0040 /** * @def pa_EF_LVL1_RECORD_VALID_DST_PORT * TCP/UDP destination port in packet should be replaced with the one in record */ #define pa_EF_LVL1_RECORD_VALID_DST_PORT 0x0080 /* @} */ /* ingroup */ /** @} */ /** * @defgroup paEfLvl1RecordCtrlFlags PA Egress Flow Level One Record Control Flag Definitions * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Level One Record Control Flag Definitions * Bitmap definition of the ctrlFlags in @ref paEfRecLevel1_t. */ /*@{*/ /** * @def pa_EF_LVL1_RECORD_CONTROL_FLAG_IP_CKSUM * Flag -- 1: Recalculate IP header Checksum */ #define pa_EF_LVL1_RECORD_CONTROL_FLAG_IP_CKSUM 0x0001 /** * @def pa_EF_LVL1_RECORD_CONTROL_FLAG_L4_CKSUM * Flag -- 1: Recalculate TCP/UDP Checksum */ #define pa_EF_LVL1_RECORD_CONTROL_FLAG_L4_CKSUM 0x0002 /** * @def pa_EF_LVL1_RECORD_CONTROL_FLAG_TTL_DEC * Flag -- 1: Decrement TTL */ #define pa_EF_LVL1_RECORD_CONTROL_FLAG_TTL_DEC 0x0004 /** * @def pa_EF_LVL1_RECORD_CONTROL_FLAG_EXP_TCP_CTRL * Flag -- 1: Detect and forward TCP control packet through egress flow exception route */ #define pa_EF_LVL1_RECORD_CONTROL_FLAG_EXP_TCP_CTRL 0x0008 /** * @def pa_EF_LVL1_RECORD_CONTROL_FLAG_EXP_IP_OPTION * Flag -- 1: Detect and forward IP packet with IPv4 options or IPv6 extension headers through egress flow exception route */ #define pa_EF_LVL1_RECORD_CONTROL_FLAG_EXP_IP_OPTION 0x0010 /** * @def pa_EF_LVL1_RECORD_CONTROL_FLAG_EXP_IP_FRAGMENT * Flag -- 1: Detect and forward fragmented IP packet through egress flow exception route */ #define pa_EF_LVL1_RECORD_CONTROL_FLAG_EXP_IP_FRAGMENT 0x0020 /** * @def pa_EF_LVL1_RECORD_CONTROL_FLAG_EXP_IP_EXPIRE * Flag -- 1: Detect and forward expired IP packet through egress flow exception route */ #define pa_EF_LVL1_RECORD_CONTROL_FLAG_EXP_IP_EXPIRE 0x0040 /*@}*/ /** @} */ /** * @ingroup palld_api_structures * @brief PA Egress Flow Level One Record data structure * * @details The PA Egress Flow level one record is used to instruct PASS to perform Inner L3/L4 Processing as specified below: * -IP header updates * - Source/Destination addresses * - TOS/Traffic Class * - Flow Label * - TTL * -IPv4 header checksum calculation * -TCP/UDP header updates * - Source/Destination Port * -TCP/UDP checksum calculation * -Inner IP Fragmentation pre-processing * * paEfRecLevel1_t defines the configuration parameters of the egress flow level one record * Since not all fields are used all the time, validBitMap is used to specify which optional field * is used for packet modification. */ typedef struct { uint16_t validBitMap;/**< Valid Bitmap corresponding to each optional field as defined at @ref paEfLvl1RecordValidBits */ uint16_t ctrlBitMap; /**< Level one record control flag Bitmap as defined at @ref paEfLvl1RecordCtrlFlags */ int ipType; /**< IP type (Mandatory if srcIp or dest Ip is sepcified) @ref IpValues */ paIpAddr_t src; /**< Source IP address */ paIpAddr_t dst; /**< Destination IP address */ uint32_t flow; /**< IPv6 flow label in 20 lsbs */ uint8_t tos; /**< IP Type of Service (IPv4) / Traffic class (IPv6) */ uint16_t mtu; /**< IP MTU size */ uint16_t srcPort; /**< TCP/UDP Source Port Number */ uint16_t dstPort; /**< TCP/UDP Destinatio Port Number */ } paEfRecLevel1_t; /** * @defgroup paIpsecProto IPSEC Protocols * @ingroup palld_api_constants * @{ * * @name IPSEC Protocols * * Parameter ipsecProto of paEfRecIpsecParams_t should be set to * one of these types. */ /*@{*/ typedef enum { pa_IPSEC_PROTO_ESP = 0, pa_IPSEC_PROTO_AH } paIpsecProto_e; /*@}*/ /** @} */ /** * @defgroup paEfRecIpsecConfigCtrlBit PA Egress Flow Record IPSEC Configuration Control Bit Definitions * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Record IPSEC Configuration Control Bit Definitions * * Bitmap definition of the ctrlBitMap in paEfRecIpsecParams_t. * */ /*@{*/ /** * @def pa_EF_RECORD_IPSEC_USE_LOC_DMA * Control Info -- 0:Use PASS global DMA to forward packets to SA (default) * 1::Use PASS local DMA to forward packets to SA */ #define pa_EF_RECORD_IPSEC_USE_LOC_DMA 0x0001 /*@}*/ /** @} */ /** * @ingroup palld_api_structures * @brief Egress Flow IPSEC Configuration Parameters structure * * Data structure defines the IPSEC specific configuration parameters within the egress flow record * */ typedef struct { uint16_t ipsecProto; /**< Specify the IPSEC protocol as defined at @ref paIpsecProto */ uint16_t ctrlBitMap; /**< Various control information as specified at @ref paEfRecIpsecConfigCtrlBit */ uint8_t encBlkSize; /**< Specify the encryption block size 1: Stream encryption and no alignment requirement 4: AES-CTR or other stream-like encryption with 4-byte alignment block size: block encryption algorithm */ uint8_t ivSize; /**< Specify the size of the initialization vector in bytes */ uint8_t macSize; /**< Specify the size of the authentication tag in bytes */ uint8_t flowId; /**< Specify the 8-bit CPPI Flow ID which instructs how the link-buffer queues are used for forwarding packets */ uint16_t queueId; /**< Specify the 16-bit SA input queue ID */ uint32_t spi; /**< Specify the SPI (Security Parameter Index) */ uint32_t saInfo0; /**< Specify SA-specific software info word 0 */ uint32_t saInfo1; /**< Specify SA-specific software info word 1 */ } paEfRecIpsecParams_t; /** * @defgroup paEfLvl2RecordValidBits PA Egress Flow Level two Record Valid Bit Definitions * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Level two Record Valid Bit Definitions * * Bitmap definition of the validBitMap in @ref paEfRecLevel2_t. */ /*@{*/ /** * @def pa_EF_LVL2_RECORD_VALID_CTRL_FLAGS * - Level two record control flags is present */ #define pa_EF_LVL2_RECORD_VALID_CTRL_FLAGS 0x0001 /** * @def pa_EF_LVL2_RECORD_VALID_IP_MTU * Outer IP MTU is specified, perform Outer IP fragmentation is necessary */ #define pa_EF_LVL2_RECORD_VALID_IP_MTU 0x0002 /** * @def pa_EF_LVL2_RECORD_VALID_IPSEC * - IPSEC parameters are present */ #define pa_EF_LVL2_RECORD_VALID_IPSEC 0x0004 /* @} */ /* ingroup */ /** @} */ /** * @defgroup paEfLvl2RecordCtrlFlags PA EgressFlow Level Two Record Control Flag Definitions * @ingroup palld_api_constants * @{ * * @name PA EgressFlow Level Two Record Control Flag Definitions * Bitmap definition of the ctrlFlags in @ref paEfRecLevel2_t. */ /*@{*/ /** * @def pa_EF_LVL2_RECORD_CONTROL_SINGLE_IP * Flag -- 1: There is only one IP layer, i.e. there is no inner IP * * @note This flag should be set in IPSEC transport mode where only one IP layer is present. */ #define pa_EF_LVL2_RECORD_CONTROL_SINGLE_IP 0x0001 /** * @def pa_EF_LVL2_RECORD_CONTROL_INSERT_IPSEC_HDR_TRAIL * Flag -- 1: Format and insert IPSEC ESP/AH header and trailer into the packets * 0: Use the IPSEC ESP/AH header and trailer existing in the packet * * @note: The option is only valid if the outer IP header is not inserted or replaced * by this record. */ #define pa_EF_LVL2_RECORD_CONTROL_INSERT_IPSEC_HDR_TRAIL 0x0002 /** * @def pa_EF_LVL2_RECORD_CONTROL_FLAG_TTL_DEC * Flag -- 1: Decrement TTL at the outer IP header */ #define pa_EF_LVL2_RECORD_CONTROL_FLAG_TTL_DEC 0x0004 /** * @def pa_EF_LVL2_RECORD_CONTROL_FLAG_EXP_IP_OPTION * Flag -- 2: Detect and forward IP packet with IPv4 options or IPv6 extension headers through egress flow exception route */ #define pa_EF_LVL2_RECORD_CONTROL_FLAG_EXP_IP_OPTION 0x0008 /** * @def pa_EF_LVL2_RECORD_CONTROL_FLAG_EXP_IP_FRAGMENT * Flag -- 1: Detect and forward fragmented IP packet through egress flow exception route */ #define pa_EF_LVL2_RECORD_CONTROL_FLAG_EXP_IP_FRAGMENT 0x0010 /** * @def pa_EF_LVL2_RECORD_CONTROL_FLAG_EXP_IP_EXPIRE * Flag -- 1: Detect and forward expired IP packet through egress flow exception route */ #define pa_EF_LVL2_RECORD_CONTROL_FLAG_EXP_IP_EXPIRE 0x0020 /*@}*/ /** @} */ /** * @ingroup palld_api_constants * @def pa_MAX_EF_REC_IP_HDR_LEN * The maximum IP Header Length in bytes within an egress flow level 2 record */ #define pa_MAX_EF_REC_IP_HDR_LEN 40 /** * @ingroup palld_api_structures * @brief PA Egress Flow Level Two Record data structure * * @details The PA Egress Flow level two record is used to instruct PASS to perform outer L3 and IPSEC Processing as specified below: * - Insert/Update outer IP header * - Update payload length * - Update protocol/nextHeader if IPSEC is enabled * - Update TTL * - IPv4 header checksum calculation * - Insert/Update IPSEC ESP/AH header * - Replace/Insert IPSEC ESP Trailer * - Replace/Insert IPSEC ESP ICV * - Complete Inner IP Fragmentation from previous stage * - Outer IP fragmentation pre-processing * * paEfRecLevel2_t defines the configuration parameters of the egress flow level two record * Since not all fields are used all the time, validBitMap is used to specify which optional field * is used for packet modification. * * @note: The egress flow level two record should be provided if outer IP is present and/or IPSEC operation is required. */ typedef struct { uint16_t validBitMap;/**< Valid Bitmap corresponding to each optional field as defined at @ref paEfLvl2RecordValidBits */ uint16_t ctrlBitMap; /**< Level two record control flag Bitmap as defined at @ref paEfLvl2RecordCtrlFlags */ uint16_t mtu; /**< Outer IP MTU size */ uint16_t ipHdrSize; /**< IP header size in bytes (0:Retain the outer IP header in the packet */ uint8_t* ipHdr; /**< Pointer to the IP header */ paEfRecIpsecParams_t ipsec; /**< IPSEC related parameters */ } paEfRecLevel2_t; /** * @defgroup paEfLvl3RecordValidBits PA Egress Flow Level Three Record Valid Bit Definitions * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Level Three Record Valid Bit Definitions * * Bitmap definition of the validBitMap in @ref paEfRecLevel3_t. */ /*@{*/ /** * @def pa_EF_LVL3_RECORD_VALID_CTRL_FLAGS * - Level three record control flags is present */ #define pa_EF_LVL3_RECORD_VALID_CTRL_FLAGS 0x0001 /** * @def pa_EF_LVL3_RECORD_VALID_IP_MTU * IP MTU is specified, perform IP fragmentation adjustment due to the extra header insertion * * @note: The MTU sise should be consistent with the one at the corresponding level 2 or level 1 * record. */ #define pa_EF_LVL3_RECORD_VALID_IP_MTU 0x0002 /** * @def pa_EF_LVL3_RECORD_VALID_IPSEC * - 1: IPSEC AH parameters are present * 0: NAT-T parameters are present */ #define pa_EF_LVL3_RECORD_VALID_IPSEC 0x0004 /* @} */ /* ingroup */ /** @} */ /** * @defgroup paEfLvl3RecordCtrlFlags PA EgressFlow Level Three Record Control Flag Definitions * @ingroup palld_api_constants * @{ * * @name PA EgressFlow Level Three Record Control Flag Definitions * Bitmap definition of the ctrlFlags in @ref paEfRecLevel3_t. */ /*@{*/ /** * @def pa_EF_LVL3_RECORD_CONTROL_REPLACE_HDR * Flag -- 1: Replace IPSEC AH or NAT-T header in the packet * 0: Format and insert IPSEC AH and NAT-T header into the packet */ #define pa_EF_LVL3_RECORD_CONTROL_REPLACE_HDR 0x0001 /*@}*/ /** @} */ /** * @ingroup palld_api_structures * @brief PA Egress Flow Level Three Record data structure * * @details The PA Egress Flow level three record is used to instruct PASS to perform IPSEC AH or IPSEC ESP NAT-T * Processing as specified below: * - Update outer IP header * - Update payload length * - Update protocol/nextHeader * - IPv4 header checksum calculation * - Insert/Update IPSEC AH header * - Insert/Update IPSEC NAT-T UDP header * - Outer IP fragmentation pre-processing * * paEfRecLevel3_t defines the configuration parameters of the egress flow level three record * Since not all fields are used all the time, validBitMap is used to specify which optional field * is used for packet modification. */ typedef struct { uint16_t validBitMap;/**< Valid Bitmap corresponding to each optional field as defined at @ref paEfLvl3RecordValidBits */ uint16_t ctrlBitMap; /**< Level three record control flag Bitmap as defined at @ref paEfLvl3RecordCtrlFlags */ uint16_t mtu; /**< Outer IP MTU size */ uint16_t srcPort; /**< Source port number of NAT-T UDP header */ uint16_t dstPort; /**< Destination port number of NAT-T UDP header */ paEfRecIpsecParams_t ipsec; /**< IPSEC related parameters */ } paEfRecLevel3_t; /** * @defgroup paEfLvl4RecordValidBits PA Egress Flow Level Four Record Valid Bit Definitions * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Level Four Record Valid Bit Definitions * * Bitmap definition of the validBitMap in @ref paEfRecLevel4_t. */ /** * @def pa_EF_LVL4_RECORD_VALID_CTRL_FLAGS * - Level four record control flags is present */ #define pa_EF_LVL4_RECORD_VALID_CTRL_FLAGS 0x0001 /** * @def pa_EF_LVL4_RECORD_VALID_802_3 * - L2 is 802.3 and the length filed offset of the 802.3 header is valid */ #define pa_EF_LVL4_RECORD_VALID_802_3 0x0002 /** * @def pa_EF_LVL4_RECORD_VALID_PPPoE * - L2 header include PPPoE and the length filed offset of PPPoE header is valid */ #define pa_EF_LVL4_RECORD_VALID_PPPoE 0x0004 /** * @def pa_EF_LVL4_RECORD_VALID_VLAN1 * - Inner VLAN (0x8100) in the packet should be replaced with the one in record * Inner VLAN (0x8100,VLAN1) should be inserted into the L2 header if it is * not in the packet. */ #define pa_EF_LVL4_RECORD_VALID_VLAN1 0x0008 /** * @def pa_EF_LVL4_RECORD_VALID_VLAN1 * - Outer VLAN (0x88a8) in the packet should be replaced with the one in record * Outer VLAN (0x88a8,VLAN2) should be inserted into the L2 header if it is * not in the packet. * */ #define pa_EF_LVL4_RECORD_VALID_VLAN2 0x0010 /** * @def pa_EF_LVL4_RECORD_VALID_MIN_PKTSIZE * - Perform tx padding check to ensure the minimum packet size as specified by minPktSize */ #define pa_EF_LVL4_RECORD_VALID_MIN_PKTSIZE 0x0020 /** * @def pa_REF_LVL4_RECORD_VALID_ROUTE_PRIORITY_TYPE * - Optional parameter priorityType when Host routing is valid */ #define pa_REF_LVL4_RECORD_VALID_ROUTE_PRIORITY_TYPE 0x0040 /* @} */ /* ingroup */ /** @} */ /** * @defgroup paEfLvl4RecordCtrlFlags PA EgressFlow Level Four Record Control Flag Definitions * @ingroup palld_api_constants * @{ * * @name PA EgressFlow Level Four Record Control Flag Definitions * Bitmap definition of the ctrlFlags in @ref paEfRecLevel4_t. */ /*@{*/ /*@}*/ /** @} */ /** * @ingroup palld_api_constants * @def pa_MAX_EF_REC_L2_HDR_LEN * The maximum Layer 2 Header Length in bytes within an egress flow level four record */ #define pa_MAX_EF_REC_L2_HDR_LEN 40 /** * @ingroup palld_api_structures * @brief PA Egress Flow Level Four Record data structure * * @details The PA Egress Flow level four record is used to instruct PASS to perform L2 Processing as specified below: * - Insert/Update L2 header * - Update 802.3 payload length * - Update PPPoE payload length * - Insert/update QinQ VLAN * - Insert/update VLAN * - Patch AH Header with the ICV from SA * - Outer IP Fragmentation * * paEfRecLevel4_t defines the configuration parameters of the egress flow level one record * Since not all fields are used all the time, validBitMap is used to specify which optional field * is used for packet modification. * * @note Egress flow level four record is mandatory for all egress flows. */ typedef struct { uint16_t validBitMap;/**< Valid Bitmap corresponding to each optional field as defined at @ref paEfLvl4RecordValidBits */ uint16_t ctrlBitMap; /**< Level four record control flag Bitmap as defined at @ref paEfLvl4RecordCtrlFlags */ uint16_t lenOffsetPPPoE; /**< offset to the PPPoE header */ uint16_t lenOffset802p3; /**< offset to the length field within 802.3 header */ uint16_t vlan1; /**< inner VLAN (0x8100) */ uint16_t vlan2; /**< outer VLAN (QinQ) */ uint16_t l2HdrSize; /**< L2 header size in bytes */ uint8_t* l2Hdr; /**< Pointer to the L2 header */ uint8_t minPktSize; /**< Minimum tx packet size: tx padding of zero is required if the length of tx packet is smaller than this value */ uint8_t dest; /**< Specify egress destination (HOST, EMAC and SRIO) */ uint8_t flowId; /**< Specify the 8-bit CPPI Flow ID which instructs how the link-buffer queues are used for forwarding packets */ uint8_t pktType_emacCtrl;/**< For destination SRIO, specify the 5-bit packet type toward SRIO For destination HOST, EMAC, specify the EMAC control @ref emcOutputCtrlBits to the network */ uint32_t swInfo0; /**< Placed in SwInfo0 for packets to host; Placed in the PS Info for packets to SRIO*/ uint32_t swInfo1; /**< Placed in the PS Info for packets to SRIO */ uint16_t queueId; /**< Specify the 16-bit egress queue ID */ uint16_t priIfType; /**< For Host route only, specify priority-based and/or interfcae-based routing mode as defined at @ref paRoutePriIntf_e */ } paEfRecLevel4_t; /** * @defgroup paEfRecordCtrlFlags PA EgressFlow Record Control Flag Definitions * @ingroup palld_api_constants * @{ * * @name PA Egress Flow Record Control Flag Definitions * Bitmap definition of the ctrlBitMap in @ref paEfRec_t. */ /*@{*/ /** * @def pa_EF_RECORD_CONTROL_ENABLE * Flag -- 0: Enable the egress flow record * 1: Disable the egress flow record */ #define pa_EF_RECORD_CONTROL_ENABLE 0x0001 /*@}*/ /** @} */ /** * @ingroup palld_api_constants * @brief Define the maximum number of PASS egress flow records * */ #define pa_MAX_EF_LVL1_RECORDS 256 #define pa_MAX_EF_LVL2_RECORDS 256 #define pa_MAX_EF_LVL3_RECORDS 256 #define pa_MAX_EF_LVL4_RECORDS 256 /** * @ingroup palld_api_structures * @brief PA Egress Flow Record data structure * * Data structure defines the configuration parameters of the egress flow record */ typedef struct { uint16_t index; /**< The record index of the egress flow table of the type specified here */ uint16_t type; /**< Egress flow record type as defined at @ref paEflowRecTypes */ uint16_t ctrlBitMap; /**< Egrss flow record control flag Bitmap as defined at @ref paEfRecordCtrlFlags */ union { paEfRecLevel1_t level1; /**< Specify the level one record */ paEfRecLevel2_t level2; /**< Specify the level two record */ paEfRecLevel3_t level3; /**< Specify the level three record */ paEfRecLevel4_t level4; /**< Specify the level four record */ } u; /**< Specify the configurtaion parameters of the specified record type */ } paEfRec_t; /** * @ingroup palld_api_functions * @brief Pa_configEflowRecords configures the egress flow records (PASS Gen2 only) * * @details This function is used to configure multiple egress flow records. Each egress flow * consists of up to 4-level of operations which are defined by the egress flow record * of each level respectively. * Refer to the egress flow record defintions for detailed actions and configuration * parameters of each record level. * * Each egress flow record is created and refered to based on its record index. * Once the record is created through a call to this function it remains effective * until this function is called again to explicitly overwrite its content. It is not * recommended to update a record when it is still used by one or more packet routes. * * The recommended Egress Flow Record update procedure is as the followings: * - Step 1: Call @ref Pa_delFcHandle to remove all egress flows which invokes * the egress flow records to be updated and wait for the corresponding * command acknowledge packet. * - Step 2: Remove all IP forwarding flows, which invoke the egress flow records * to be updated, in the ingress path. * - Step 3: Wait for a short period of time such as 1us to allow the remaining * egress packets to pass through the PASS. * - Step 4: Call this API to re-configure the egress flow records. * * @param[in] iHandle The driver instance handle * @param[in] nRecords The number of egress flow records specified * @param[out] nRecProc The number of egress flow records processed successfuly * @param[in] records Array of egress flow records * @pre A driver instance must be created and tables initialized * * @note: This API is not supported at the first generation PASS */ paReturn_t Pa_configEflowRecords (Pa_Handle iHandle, int nRecords, int *nRecProc, paEfRec_t *records ); /** * @defgroup paFcInfoValidBit PA Flow Cache Matching Info Valid Bit Definitions * @ingroup palld_api_constants * @{ * * @name PA Flow Cache Matching Info Valid Bit Definitions * Bitmap definition of the validBitfield in paFcInfo_t. * It allows selective Flow Cache matching parameters */ /*@{*/ /** * @def pa_FC_INFO_VALID_SRC_IP * srcIp is present */ #define pa_FC_INFO_VALID_SRC_IP 0x0001 /** * @def pa_FC_INFO_VALID_SRC_IP_MASK * srcIpMask is present. This flag is valid only if srcIp is present. * If srcIp is present and this flag is clear, it means all IP address bits are valid. * @note: only IP subnet mask is supported. */ #define pa_FC_INFO_VALID_SRC_IP_MASK 0x0002 /** * @def pa_FC_INFO_VALID_DST_IP * dstIp is present */ #define pa_FC_INFO_VALID_DST_IP 0x0004 /** * @def pa_FC_INFO_VALID_DST_IP_MASK * dstIpMask is present. This flag is valid only if dstIp is present. * If dstIp is present and this flag is clear, it means all IP address bits are valid. * @note: only IP subnet mask is supported. */ #define pa_FC_INFO_VALID_DST_IP_MASK 0x0008 /** * @def pa_FC_INFO_VALID_CTRL_FLAG * ctrlFlag and ctrlFlagMask are present */ #define pa_FC_INFO_VALID_CTRL_FLAG 0x0010 /** * @def pa_FC_INFO_VALID_PROTO * proto is present */ #define pa_FC_INFO_VALID_PROTO 0x0020 /** * @def pa_FC_INFO_VALID_DSCP * dscp is present */ #define pa_FC_INFO_VALID_DSCP 0x0040 /** * @def pa_FC_INFO_VALID_SRC_PORT * srcPortBegin and srcPortEnd are present */ #define pa_FC_INFO_VALID_SRC_PORT 0x0100 /** * @def pa_FC_INFO_VALID_DST_PORT * dstPortBegin and dstPortEnd are present */ #define pa_FC_INFO_VALID_DST_PORT 0x0200 /*@}*/ /** @} */ /** * @defgroup paFcInfoCtrlFlags PA Flow Cache Info Control Flag Definitions * @ingroup palld_api_constants * @{ * * @name PA Flow Cache Info Control Flag Definitions * Bitmap definition of the ctrlFlags and ctrlFlagsMask in @ref paFcInfo_t. */ /*@{*/ /** * @def pa_FC_INFO_CONTROL_FLAG_FRAG * Flag -- 1: IP fragments */ #define pa_FC_INFO_CONTROL_FLAG_FRAG 0x0001 /** * @def pa_FC_INFO_CONTROL_FLAG_CONTAIN_L4 * Flag -- 1: Packet or fragment which conatins L4 header */ #define pa_FC_INFO_CONTROL_FLAG_CONTAIN_L4 0x0002 /*@}*/ /** @} */ /** * @ingroup palld_api_structures * @brief Flow cache lookup information * * @details paFcInfo_t is used to specifiy the Flow cache matching parameters. */ typedef struct { uint16_t validBitMap; /**< Specify valid parameters as defined at @ref paFcInfoValidBit */ uint16_t ctrlFlag; /**< Specify Flow Cache control flags as defined at @ref paFcInfoCtrlFlags */ uint16_t ctrlFlagMask; /**< Flow Cache control flag valid masks */ uint16_t ipType; /**< @ref IpValues */ paIpAddr_t srcIp; /**< Source IP address */ paIpAddr_t srcIpMask; /**< Source IP subnet mask*/ paIpAddr_t dstIp; /**< Destination IP address */ paIpAddr_t dstIpMask; /**< Destination IP subnet mask */ uint8_t proto; /**< IP Protocol (IPv4) / Next Header (IPv6) */ uint8_t dscp; /**< DSCP value */ uint16_t srcPortBegin; /**< Minimum Source Port Number */ uint16_t srcPortEnd; /**< Maximum Source Port Number */ uint16_t dstPortBegin; /**< Minimum Destinatio Port Number */ uint16_t dstPortEnd; /**< Maximum Destinatio Port Number */ } paFcInfo_t; /** * @ingroup palld_api_structures * @brief PA Flow Cache Entry Statistics Structure * * @details This structures define the PA Flow Cache per-entry statistics provided * with API function @ref Pa_queryFcStats (). */ typedef struct paFcStats_s { uint32_t nMatchPackets; /**< Number of packets which matchs the ACL rule */ } paFcStats_t; /** * @ingroup palld_api_functions * @brief Pa_addFc adds a Flow Cache entry to the Flow Cache table (PASS Gen2 only) * * @details This function is used to add or replace an entry in the Flow Cache table. * A new entry is added if the Flow Cache configuration does not match the value of any existing entry * in the module handle table. If the Flow Cache configuration is same of an existing entry then the * egress flow operation information for the existing entry is changed to the values provided with the * input parameter efOpInfo. * * The caller can also force the existing entry to be replaced by the new one by passing the handle of * the existing entry through retHandle. * * On return the command buffer (cmd) contains a formatted command for the sub-system. The * destination for the command is provided in cmdDest. The module user must send the formatted * command to the sub-system. The sub-system will generate a reply and this reply must be * sent back to this module through the API @ref Pa_forwardResult. * * The flow cache entry should be deleted by invoking API @ref Pa_delFcHandle. * @note The existing entry can not be replaced when it is still at pending response state. The return code * pa_INVALID_DUP_ENTRY or pa_PENDING_FC_ENTRY will be used in this case. * * @param[in] iHandle The driver instance handle * @param[in] index Specify the index of the LUT1 entry (0-63). Set to pa_LUT1_INDEX_NOT_SPECIFIED if not specified * @param[in] efOpInfo Specify egress flow operation per match as @ref paEfOpInfo_t * @param[in] fcInfo Value @ref paFcInfo_t * @param[out] retHandle Pointer to the returned FC handle * @param[out] cmd Buffer where the PASS command is created * @param[in] cmdSize The size of the cmd buffer * @param[in] reply Where the response to the PASS command is routed * @param[out] cmdDest Value (@ref cmdTxDest) * @retval Value (@ref ReturnValues) * @pre A driver instance must be created and tables initialized * * @note: This API is not supported at the first generation PASS */ paReturn_t Pa_addFc (Pa_Handle iHandle, int index, paEfOpInfo_t *efOpInfo, paFcInfo_t *fcInfo, paHandleFc_t *retHandle, paCmd_t cmd, uint16_t *cmdSize, paCmdReply_t *reply, int *cmdDest ); /** * @ingroup palld_api_functions * @brief Pa_delFcHandle deletes a Flow Cache handle (PASS Gen2 only) * * @details This function is used to remove an entry from the LUT1-FC lookup table * * @param[in] iHandle The driver instance handle * @param[in] handle Pointer to the FC handle to delete * @param[out] cmd Where the created command is placed * @param[in] cmdSize The size of the cmd buffer * @param[in] reply Where the sub-system sends the command reply * @param[out] cmdDest Value (@ref cmdTxDest) * @retval Value (@ref ReturnValues) * @pre A driver instance must be created and tables initialized * * @note: This API is not supported at the first generation PASS */ paReturn_t Pa_delFcHandle (Pa_Handle iHandle, paHandleFc_t *handle, paCmd_t cmd, uint16_t *cmdSize, paCmdReply_t *reply, int *cmdDest ); /** * @ingroup palld_api_functions * @brief Pa_queryFcStats queries Flow Cache per-entry statistics (PASS Gen2 only) * * @details This function is used to query the Flow Cache per-entry statistics. * The statistics can be optionally cleared after reading through the doClear parameter. * * @param[in] iHandle The driver instance handle * @param[in] fcHandle The FC handle * @param[in] doClear If TRUE then stats are cleared after being read * @param[out] pFcStats Pointer to the FcStats buffer * @retval Value (@ref ReturnValues) * @pre A driver instance must be created and tables initialized * * @note: This API is not supported at the first generation PASS */ paReturn_t Pa_queryFcStats (Pa_Handle iHandle, paHandleFc_t fcHandle, uint16_t doClear, paFcStats_t *pFcStats); #ifdef __cplusplus } #endif #endif /* _PA_FC_H */