ti/runtime/netapi/netcp_cfg.h

   1 /***************************************************
   2  * File: netcp_cfg.h
   3  * Purpose: netcp config API
   4  **************************************************************
   5  *@file netcp_cfg.h
   6  *
   7  * @brief DESCRIPTION:  netapi NETCP configuration API header  file
   8  *          for user space transport library
   9  *
  10  * REVISION HISTORY:  rev 0.0.1
  11  *
  12  *  Copyright (c) Texas Instruments Incorporated 2010-2011
  13  *
  14  *  Redistribution and use in source and binary forms, with or without
  15  *  modification, are permitted provided that the following conditions
  16  *  are met:
  17  *
  18  *    Redistributions of source code must retain the above copyright
  19  *    notice, this list of conditions and the following disclaimer.
  20  *
  21  *    Redistributions in binary form must reproduce the above copyright
  22  *    notice, this list of conditions and the following disclaimer in the
  23  *    documentation and/or other materials provided with the
  24  *    distribution.
  25  *
  26  *    Neither the name of Texas Instruments Incorporated nor the names of
  27  *    its contributors may be used to endorse or promote products derived
  28  *    from this software without specific prior written permission.
  29  *
  30  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  31  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  32  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  33  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  34  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  35  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  36  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  37  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  38  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  39  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  40  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  41
  42  ***************************************************/
  43
  44 #ifndef __NETCP_CFG__H
  45 #define __NETCP_CFG__H
  46
  47 #include "netapi.h"
  48 #include "ti/drv/pa/pa.h"
  49 #include "ti/runtime/pktlib/pktlib.h"
  50
  51 //NETCP FLOW
  52 typedef struct NETCP_CFG_FLOW_Tag
  53 {
  54         int flowid;
  55 } NETCP_CFG_FLOW_T;
  56 typedef void *  NETCP_CFG_FLOW_HANDLE_T;
  57 #define NETCP_DEFAULT_FLOW  (NETCP_CFG_FLOW_HANDLE_T*) NULL
  58
  59 //NETCP ROUTE
  60 typedef struct NETCP_CFG_ROUTE_Tag
  61 {
  62    NETCP_CFG_FLOW_T * p_flow;  //NULL or NETCP_DEFAULT_FLOW for default flow
  63    PKTIO_HANDLE_T * p_dest_q;       //NULL for default destination queue
  64 } NETCP_CFG_ROUTE_T;
  65 typedef void * NETCP_CFG_ROUTE_HANDLE_T;
  66 #define NETCP_DEFAULT_ROUTE  (NETCP_CFG_ROUTE_HANDLE_T*) NULL
  67
  68
  69 /*--------------flow management--------*/
  70 NETCP_CFG_FLOW_HANDLE_T netcp_cfgAddFlow(NETAPI_T ,
  71                                             int n,
  72                                             Pktlib_HeapHandle handles[],
  73                                             int sizes[], //must be<= heap corresponding heap size-recv_offset-any desired tail room
  74                                             int recv_offset,  //bytes to save in front of packet
  75                                             int * err );
  76 void netcp_cfgDelFlow(NETAPI_T , NETCP_CFG_FLOW_HANDLE_T , int * err);
  77
  78 /*-----------Actions----------*/
  79 #define NETCP_CFG_ACTION_DISCARD 0
  80 #define NETCP_CFG_ACTION_CONTINUE 1  //pass packet on to next classifier
  81 #define NETCP_CFG_ACTION_TO_SW    2
  82
  83 /*------------L2----------------------*/
  84 typedef void * NETCP_CFG_VLAN_T;
  85
  86 /******************************************************************/
  87 /***********************APP ids for rx meta data********************/
  88 /******************************************************************/
  89
  90 /* APPIDs are present in RX packet meta data and tell "how far the packet got
  91    through the classification rules of NETCP
  92    APPID is 32 bits:
  93       bits 31-24 = MATCH STAGE (NETAPI_NECP_MATCH_xxx below)
  94       bits 23-8  = identifier (depends on match stage)
  95       bits  7-0  = logical mac interface
  96
  97    As a cheat sheet:
  98 If APPID == _NETCP_MATCH_GENERIC_MAC  then
  99    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.
 100    Packet did not match any other rule
 101
 102 If APPID == _NETCP_MATCH_GENERIC_IP  then
 103    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
 104    packet matched a generic IP rule attached to that interface.  The IP rule # for the interface
 105    is given in Bytes 3,2 of the APPID.   Packet did not match any other rule
 106
 107 If APPID = NETCP_MATCH_CLASS
 108    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
 109    packet matched a generic IP rule  attached to that interface OR a general IP rule added as part of
 110    the classifier or it matched a combination of ISPEC SA rule and a policy check.  Finally,
 111    Packet matched a L4 port rule that was added as part of a classifer.  Bytes 3-2
 112    give the ID of the classifier . Packet did not match any other rule
 113
 114 If APPID = NETCP_MATCH_CLASS_L3   (partial classifier match)
 115    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
 116    packet matched a general IP rule added as part of a classifier.  But it not match a
 117    L4 port or any other rule. We cannout say what classifer partially matched so Bytes 3-2 are
 118    not applicable
 119
 120
 121 If APPID = NETCP_MATCH_IPSEC
 122    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
 123    packet matched an IPSEC SA  rule (matched proto, dest ip and SPI).  The SA id  is in
 124    bytes 3-2 of APPID.  Packet did not match any other rule (so may have failed a policy check)
 125
 126 ID APPID = NETCP_MATCH_IPSEC_POLICY
 127    packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
 128    packet matched an IPSEC SA rule (matched proto, dest ip and SPI).  Packet matched
 129    a POLICY RULE - this is a check of the inner IP.  The IPSEC RX Policy ID  is in
 130    bytes 3-2 of APPID.  Packet did not match any other rule
 131 */
 132
 133
 134 // NWAL "AP ids" for PA Rules that are added
 135 #define NETAPI_NETCP_MATCH_GENERIC_MAC  0x10000000  //lower byte==interface
 136 #define NETAPI_NETCP_MATCH_GENERIC_IP   0x20000000  //lower byte==interface
 137 #define NETAPI_NETCP_MATCH_CLASS        0x80000000  //FULL MATCH or' in classifier (16 bits), lower byte==interface
 138 #define NETAPI_NETCP_MATCH_CLASS_L3     0x40000000  //MATCHED L3 but not L4.  lower byte==interface
 139 #define NETAPI_NETCP_MATCH_IPSEC        0x01000000  //lower byte==interface, Or' in SA id (16 bits)
 140 #define NETAPI_NETCP_MATCH_IPSEC_POLICY 0x02000000  //lower byte==interface, Or' in SA id (16 bits)
 141
 142 /*---------MAC APPID------------------*/
 143 /* Packets just matching MAC rule are tagged with this type (MATCH_GENERIC_MAC) */
 144 typedef uint32_t NETCP_CFG_MACIF_T;
 145
 146 /*---------------IP APPID-------------------*/
 147 /* Packets whose final match is an IP rule are tagged with this type (MATCH_GENERIC_IP)*/
 148 typedef uint32_t NETCP_CFG_IP_T;
 149
 150 /*--------------Tunnel APPID------------------*/
 151 /* Packets whose final match a IPSEC tunnel  are tagged with this type (MATCH_IPSEC)*/
 152 typedef uint32_t NETCP_CFG_SA_T;
 153
 154 /*---------------IPSEc RX Policy APPID------------*/
 155 /* Packets whose final match is a IPSEC RX Policy  are tagged with this type (MATCH_IPSEC_POLICY)*/
 156 typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 157
 158
 159 //use this in AddIp, AddClassifier to indicate any MAC address
 160 #define NETCP_CFG_NO_INTERFACE 0xff
 161
 162 /* del mac i/f */
 163 void netcp_cfgDelMac(NETAPI_T h,int iface_no,  int *err);
 164
 165 /* del attached IP*/
 166 void netcp_cfgDelIp(NETAPI_T h, int iface_no,  nwal_IpType ipType,
 167                   nwalIpAddr_t  * ip_addr,
 168                   nwalIpOpt_t * ip_qualifiers,
 169                   NETCP_CFG_IP_T,
 170                   int *err);
 171
 172
 173 /*****************************************************************
 174  * Create a  MAC interface
 175  ****************************************************************/
 176 /*
 177 *  @brief  API Creates a MAC interface
 178  *
 179  *  @details This api is used to create a MAC interface.
 180  *      Once it is created, the MAC interface can be used to receive packets. The API
 181  *      adds a rule to the NETCP 1st level lookup tables to route all packets with destination
 182  *      MAC matching supplied argument and not matching any other lookup entry (see @ref netcp_cfgAddIp) to
 183  *      the supplied route, @ref NETCP_CFG_ROUTE_T, (or default route).
 184  *      Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_MAC
 185  *  Note: The internal SOC switch must be "taught" that this mac
 186  *      address is present by transmitting a packet with destination mac = this interface mac address.
 187  *  @param[in]  @ref NETAPI_T: NETAPI instance
 188  *  @param[in]  char *: pointer to 6 byte MAC address for interface
 189  *  @param[in]  int : interface number (0,1,..)
 190  *  @param[in]  int : switch port (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported]
 191  *  @param[in]  @ref NETCP_CFG_ROUTE_HANDLE_T : [future] handle of a created route or NULL to use internal default route
 192  *  @oaram[in]  @ref NETCP_CFG_VLAN_T : [future[ vlan configuration . Set to NULL
 193  *  @param[in]  int : [future] interface state (0=down, 1= up)
 194  *  @param[out] int * err:  pointer to error return
 195  *  @retval     @ref NETCP_CFG_MACIF_T : returned AppID for interface (this is returned in meta data for
 196  *                 received packets matching this rule an no others)
 197  *  @pre       @ref netapi_init
 198  */
 199 NETCP_CFG_MACIF_T  netcp_cfgCreateMacInterface(
 200                   NETAPI_T  h,     //
 201                   uint8_t *p_mac, //mac address associated with interface
 202                   int iface_no, //0,1, ..
 203                   int switch_port,//0=don't care, 1=switch port 1, 2=switch port 2 , ..
 204                   NETCP_CFG_ROUTE_HANDLE_T  route, //NULL to use default
 205                   NETCP_CFG_VLAN_T  vlan,  //future
 206                   int state,  //0=down, 1=up  //FUTURE
 207                   int * err
 208                   );
 209
 210 /*****************************************************************
 211  * Add IP address/qualifier to MAC interface
 212  ****************************************************************/
 213 /*
 214 *  @brief  API attaches an IP adderess and qualifier to a MAC interface
 215  *
 216  *  @details This api is used to add an IP address to a MAC interface along
 217  *           with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default
 218  *            may be specified to indicate where to send packets matching the MAC interface MAC address, the
 219  *            supplied IP address and any qualifier.  This API adds a rule to the NETCP level 1 lookup tables
 220  *            Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_IP
 221  * Note: An IP address must be attached to enable NETCP Recevie Checksum offload feature
 222  *  @param[in]  @ref NETAPI_T: NETAPI instance
 223  *  @param[in]  int : interface number (0,1,..)
 224  *  @param[in]  @ref nwal_IpType : type of IP address (V4 for V6)
 225  *  @oaram[in]  @ref nwalIpAddr_t : ip_address
 226  *  @param[in]  @ref nwalIpOpt_t : ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
 227  *                  diffserv category for example
 228  *  @param[in]  @ref NETCP_CFG_ROUTE_HANDLE_T : [future] handle of a created route or NULL to use internal default route
 229  *  @param[out] int * err:  pointer to error return
 230  *  @retval     @ref NETCP_CFG_IP_T : returned AppID for attached rule. This is returned in RX meta data for
 231  *              packets matching this rule and no other.
 232  *  @pre       @ref netapi_init , @ref netcp_cfgAddMac
 233  */
 234 NETCP_CFG_IP_T  netcp_cfgAddIp(
 235                   NETAPI_T  h,
 236                   int  iface_no,
 237                   nwal_IpType ipType,
 238                   nwalIpAddr_t  * ip_addr,
 239                   nwalIpOpt_t * ip_qualifiers,
 240                   NETCP_CFG_ROUTE_HANDLE_T  route,  //NULL for default
 241                   int * err
 242                   );
 243 #define netcp_addIp netcp_cfgAddIp //oops
 244
 245 /*------------------classification API-------------------*/
 246
 247 //handle to installed classifier returned by API.  Pkts matching
 248 //this classifier will have meta data with this tag.  Also used
 249 //to delete classifier
 250 typedef uint32_t NETCP_CFG_CLASS_T;
 251
 252 //classifier L4 type  (L2,L3 implied by iface, ip)
 253 typedef struct NETCP_CFG_CLASS_L4_Tag
 254 {
 255         //which mac interface pkt is from,
 256         int iface;
 257         NETCP_CFG_IP_T  ip;
 258
 259         //L4  (port)
 260         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
 261         nwalAppProto_t   appProto;   //ports or equivalent
 262
 263 } NETCP_CFG_CLASS_L4_T;
 264
 265 //classifier L4 + policy  (L2, L3 (outer), tunnel, L3 (inner)  implied by policy
 266 typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
 267 {
 268         //which mac interface pkt is from,
 269         int iface;
 270         NETCP_CFG_IPSEC_POLICY_T  ip_policy;
 271
 272         //L4  (port)
 273         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
 274         nwalAppProto_t   appProto;   //ports or equivalent
 275
 276 } NETCP_CFG_CLASS_L4_IPSEC_T;
 277
 278
 279 //classifier L3_L4 type (L2 implied by iface)
 280 typedef struct NETCP_CFG_CLASS_L3_L4_Tag
 281 {
 282         //which mac interface pkt is from,
 283         int iface;
 284
 285         //L3 -  iP address: IP type, destination addr, qualifiers
 286         nwal_IpType ipType;
 287         nwalIpAddr_t  * ip_addr;
 288         nwalIpOpt_t * ip_qualifiers;
 289         NETCP_CFG_ROUTE_HANDLE_T p_fail_route; //what to do if L3 matches but L4 fails AND L3 is a
 290                                               // new rule.(if exisitng rule, then existing fail
 291                                               //route will be used.
 292
 293         //L4  (port)
 294         nwal_appProtoType_t proto;   //L4 proto  (-1 for don't care)
 295         nwalAppProto_t   appProto;   //ports or equivalent
 296
 297 } NETCP_CFG_CLASS_L3_L4_T;
 298
 299 //classifier
 300 typedef struct NETCP_CFG_CLASSIFIER_Tag
 301 {
 302         int classType;
 303 #define NETCP_CFG_CLASS_TYPE_L4  0
 304 #define NETCP_CFG_CLASS_TYPE_L3_L4  1
 305         union
 306         {
 307                 NETCP_CFG_CLASS_L3_L4_T  c_l3_l4;
 308                 NETCP_CFG_CLASS_L4_T  c_l4;
 309                 NETCP_CFG_CLASS_L4_IPSEC_T  c_l4_ipsec;
 310         } u;
 311
 312 } NETCP_CFG_CLASSIFIER_T;
 313
 314 //Instert a classifier.
 315 NETCP_CFG_CLASS_T netcp_cfgAddClass(NETAPI_T h,
 316                                     NETCP_CFG_CLASSIFIER_T *p_class,
 317                                     NETCP_CFG_ROUTE_HANDLE_T p_route,
 318                                     int action, int * err);
 319 //delete classifier
 320 void netcp_cfgDelClass(NETAPI_T h,
 321                          NETCP_CFG_CLASS_T classId,
 322                          int *err);
 323
 324
 325
 326 /***************************************************************************
 327 ********************************STATS**************************************
 328 **************************************************************************/
 329
 330 /*
 331  *  @brief  This is the callback function that is used to return statistics from NETCP
 332  *
 333  *  @details The application provides a callback function that NETAPI  uses to report statistics.
 334 *    The request for stats is generated from the @ref netcp_cfgReqStats API.
 335  *   Note: to receive ths stats callback, the @ref netapi_netcpPoll funcition must be called
 336  *  @param[in]  @ref NETAPI_T: NETAPI instance
 337  *  @param[in]  @ref paSysStats_t * : the PA (NETCP packet accelerator subsystem) statistics block
 338  *  @retval     none
 339  *  @pre       @ref netapi_init , @ref netapi_cfgReqStats, @ref netapi_netcpPoll
 340  */
 341 //stats CB
 342 typedef void (*NETCP_CFG_STATS_CB)( NETAPI_T h, paSysStats_t* pPaStats);
 343
 344
 345 //stats request
 346 /*
 347  *  @brief  API request statistics from NETCP
 348  *
 349  *  @details This api is used to request a statistics from NETCP.  This will generate a stats request
 350  *           command to NETCP. Sometime later, the statistics result will arrive and will be passed to
 351  *           the caller via the asynchronus callback @ref NETCP_CFG_STATS_CB that is registered in this call.
 352  *       Note: to receive the stats callback, the @ref netapi_netcpPoll funcition must be called
 353  *  @param[in]  @ref NETAPI_T: NETAPI instance
 354  *  @param[in]  @ref NETCP_CFG_STATS_CB : the function to call with the resulting statistics block
 355  *  @param[in]  int :  clear the stats in NETCP after the report (0=no, 1=yes)
 356  *  @param[out] int * err:  pointer to error return
 357  *  @retval     none
 358  *  @pre       @ref netapi_init
 359  */
 360 void netcp_cfgReqStats(NETAPI_T  h,  //NEAPI instance
 361                        NETCP_CFG_STATS_CB c, //stats report callback function
 362                        int doClear,   //0: don't clear, 1 clear
 363                        int *err);
 364
 365 #endif
 366