Additional doxygen updates
[keystone-rtos/netapi.git] / ti / runtime / netapi / netcp_cfg.h
index 8a61e16967db74b6b6290c1211e99b1afac73bb7..672d2b486b66010c4ead5000f8b9499a6284f0ad 100755 (executable)
@@ -56,7 +56,7 @@
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup cfg_structures
  *  @brief CPPI flow ID for default case, use NETCP_DEFAULT_FLOW
  */
 typedef struct NETCP_CFG_FLOW_Tag
@@ -65,15 +65,62 @@ typedef struct NETCP_CFG_FLOW_Tag
 } NETCP_CFG_FLOW_T;
 
 
+/**
+ *  @ingroup cfg_structures
+ *  @brief NETAPI configuration information
+ *
+ *  @details The parameters in this structure are used to configure NETAPI.
+ */
+typedef struct NETAPI_CFG_Tag
+{
+ int def_mem_size;                  /**<  Bytes of CMA memory we have allocated */
+ int def_flow_pkt_rx_offset;        /**<  Offset in pkt buffer for hw to start RX */
+ int def_max_descriptors;           /**<  Number of descriptors in system  (must be power of 2), 2^14 max */
+ int def_tot_descriptors_for_us;    /**<  Number of descriptors to create in our region (must be power of 2)*/
+ int def_heap_n_descriptors;        /**<  Number of descriptor plus buffers in default heap*/
+ int def_heap_n_zdescriptors;       /**<  Number of zero len descriptors in defaut heap*/
+ int def_heap_buf_size;             /**<  Size of buffers in default heap, max amount of area for packet data */
+ int def_heap_tailroom_size;        /**<  Size of tailroom in reserve */
+ int def_heap_extra_size;           /**<  Size of extra space at end of buffer */ 
+}  NETAPI_CFG_T;
+
+/* @note:
+   each buffer will be allocated:  def_heap_buf_size+def_heap_extra_size bytes
+   each descriptor attached to these buffers will have rigBufferLen of:
+      def_heap_buf_size.
+   for default RX flow,  for rx packet, the bufptr  will be def_flow_pkt_rx_offset.
+   for detault RX flow,  threshold (ie max # of bytes in buffer) will be:
+       def_heap_buf_size - def_heap_tailroom_size-def_flow_pkt_rx_offset
+
+
+ RX Packet from NetCP
+
+Headroom [Application]     Packet [HW]                Tailroom [Application]    Extra Space [Application]
+<-----------------------><--------------------------><------------------------><----------------------->
+
+Cppi_HostDesc->origBufferLen
+<----------------------------------------------------------------------------->
+Cppi_HostDesc->origBuffPtr
+|
+\/
+|------------def_heap_buf_size-------------------------------------------------|--def_heap_extra_size--|
+| def_flow_pkt_rx_offset| max Cppi_HostDesc->buffLen | def_heap_tailroom_size  |   Extra Size          |
+                        ^
+                        |
+                     Cppi_HostDesc->buffPtr
+
+
+*/
+
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @brief  This defines the handle to NETCP configuration flow.
  */
 typedef void *  NETCP_CFG_FLOW_HANDLE_T;
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETCP_DEFAULT_FLOW
  *      This defines the NETCP default FLOW to be NULL.
  */
@@ -81,7 +128,7 @@ typedef void *  NETCP_CFG_FLOW_HANDLE_T;
 
 
 /**
- * @ingroup nwal_api_constants
+ * @ingroup cfg_constants
  * @brief  Handle to the default NETCP route.
  * @details Application to use this handle to identify default NETCP route.
  */
@@ -95,30 +142,30 @@ typedef void * NETCP_CFG_ROUTE_HANDLE_T;
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup cfg_structures
  *  @brief NETCP application defined route information.
  *
  */
 typedef struct NETCP_CFG_ROUTE_Tag
 {
    NETCP_CFG_FLOW_T * p_flow;   /**< NULL or NETCP_DEFAULT_FLOW for default flow, @ref NETCP_CFG_FLOW_T */
-   PKTIO_HANDLE_T * p_dest_q;/**<NULL for default destination queue */
+   PKTIO_HANDLE_T * p_dest_q;   /**<NULL for default destination queue */
 } NETCP_CFG_ROUTE_T;
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETCP_CFG_ACTION_DISCARD
  *      This defines the NETCP action to discard packet.
  */
 #define NETCP_CFG_ACTION_DISCARD 0
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def  NETCP_CFG_ACTION_CONTINUE
  *      This defines the NETCP action to pass packet ono the next classifier
  */
 #define NETCP_CFG_ACTION_CONTINUE 1
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETCP_CFG_ACTION_TO_SW
  *      This defines the NETCP action to pass packet to User space application
  */
@@ -126,20 +173,20 @@ typedef struct NETCP_CFG_ROUTE_Tag
 
 
 /**
- * @ingroup nwal_api_constants
+ * @ingroup cfg_constants
  * @brief  Handle to the default NETCP route.
  * @details Application to use this handle to identify default NETCP route.
  */
 typedef void * NETCP_CFG_VLAN_T;
 
 /**
- * @ingroup nwal_api_constants
+ * @ingroup cfg_constants
  * @brief  AppID for MAC interface
  */
 typedef uint32_t NETCP_CFG_MACIF_T;
 
 /**
- * @ingroup nwal_api_constants
+ * @ingroup cfg_constants
  * @brief AppID for IP interface
  */
 typedef uint32_t NETCP_CFG_IP_T;
@@ -147,21 +194,21 @@ typedef uint32_t NETCP_CFG_IP_T;
 
 
 /**
- * @ingroup nwal_api_constants
+ * @ingroup cfg_constants
  * @brief This define is used to identify the application id associated with a created SA
  */
 typedef uint32_t NETCP_CFG_SA_T;
 
 
 /**
- * @ingroup nwal_api_constants
+ * @ingroup cfg_constants
  * @brief AppId used to identify NETCP IPSEC policy
  */
 typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 
 
 /**
- * @ingroup nwal_api_constants
+ * @ingroup cfg_constants
  * @def NETCP_CFG_NO_INTERFACE
  *      This define is to be used in AddIp, AddClassifier to indicate any MAC address.
  */
@@ -179,15 +226,15 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 */
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETAPI_NETCP_MATCH_GENERIC_MAC
- *      This define is used to indicate that apacket matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.  
+ *      This define is used to indicate that apacket matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.
  *      Packet did not match any other rule
  */
 #define NETAPI_NETCP_MATCH_GENERIC_MAC  0x10000000  //lower byte==interface
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETAPI_NETCP_MATCH_GENERIC_IP
  *      This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
  *      packet matched a generic IP rule attached to that interface.  The IP rule # for the interface
@@ -197,7 +244,7 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETAPI_NETCP_MATCH_CLASS
  *      This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
  *      packet matched a generic IP rule  attached to that interface OR a general IP rule added as part of
@@ -208,7 +255,7 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 #define NETAPI_NETCP_MATCH_CLASS        0x80000000  //FULL MATCH or' in classifier (16 bits), lower byte==interface
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETAPI_NETCP_MATCH_CLASS_L3
  *      This define is used to indicate that a  packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
  *      packet matched a general IP rule added as part of a classifier.  But it not match a
@@ -218,7 +265,7 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 #define NETAPI_NETCP_MATCH_CLASS_L3     0x40000000  //MATCHED L3 but not L4.  lower byte==interface
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETAPI_NETCP_MATCH_IPSEC
  *      This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
  *      packet matched an IPSEC SA  rule (matched proto, dest ip and SPI).  The SA id  is in
@@ -227,7 +274,7 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 #define NETAPI_NETCP_MATCH_IPSEC        0x01000000  //lower byte==interface, Or' in SA id (16 bits)
 
 /**
- * @ingroup netapi_constants
+ * @ingroup cfg_constants
  * @def NETAPI_NETCP_MATCH_IPSEC_POLICY
  *      This define is used to indicate that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID
  *      packet matched an IPSEC SA rule (matched proto, dest ip and SPI).  Packet matched
@@ -241,7 +288,7 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief netcp_cfgAddFlow   API to add a flow
  * 
  *  @details This api is used to add a flow
@@ -263,7 +310,7 @@ NETCP_CFG_FLOW_HANDLE_T netcp_cfgAddFlow(NETAPI_T h,
 
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief netcp_cfgDelFlow   API to delete a flow
  * 
  *  @details This api is used to delete a flow
@@ -278,7 +325,7 @@ void netcp_cfgDelFlow(NETAPI_T h ,
                                             int * err);
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief netcp_cfgDelMac   API to delete MAC  interface
  * 
  *  @details This api is used to delete a MAC interface
@@ -293,7 +340,7 @@ void netcp_cfgDelMac(NETAPI_T h,int iface_no,  int *err);
 
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief  API attaches an IP adderess and qualifier to a MAC interface
  * 
  *  @details This api is used to add an IP address to a MAC interface along
@@ -324,7 +371,7 @@ NETCP_CFG_IP_T  netcp_cfgAddIp(
                   );
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief netcp_cfgDelIp   API to delete IP interface
  * 
  *  @details This api is used to delete an IP interface
@@ -348,7 +395,7 @@ void netcp_cfgDelIp(NETAPI_T h, int iface_no,  nwal_IpType ipType,
 
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief netcp_cfgCreateMacInterface  API to create a MAC interface
  * 
  *  @details This api is used to create a MAC interface.
@@ -390,7 +437,7 @@ typedef uint32_t NETCP_CFG_CLASS_T;
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup cfg_structures
  *  @brief NETAPI Class L4 Configuration
  *
  *  @details This structure contains Class L4 Configuration. L2,L3 implied by iface, ip
@@ -406,7 +453,7 @@ typedef struct NETCP_CFG_CLASS_L4_Tag
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup cfg_structures
  *  @brief NETAPI Classifier L4 plus IPSEC policy configuration
  *
  *  @details This structure contains Class L4 plus IPSEC policy configuration. L2,L3 implied by iface, ip
@@ -425,7 +472,7 @@ typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup cfg_structures
  *  @brief NETAPI Classifier L4/L3 configuration
  *
  *  @details This structure contains Class L4 and Class L3 configuration. L2 implied by iface
@@ -444,25 +491,35 @@ typedef struct NETCP_CFG_CLASS_L3_L4_Tag
 } NETCP_CFG_CLASS_L3_L4_T;
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup cfg_structures
  *  @brief NETAPI Classifier configuration
  *
  *  @details This structure contains the NETAPI classifer configuration
  */
 typedef struct NETCP_CFG_CLASSIFIER_Tag
 {
-    int classType;              /**< Classifier type */
+
+/**
+ * Classifer type which can be set to one of the following defines:
+ * <br>
+ *      @ref NETCP_CFG_CLASS_TYPE_L4 , @ref NETCP_CFG_CLASS_TYPE_L3_L4
+ */
+    int classType;
+
 /**
  * @def NETCP_CFG_CLASS_TYPE_L4
- *      This defines classifier type to be Class L4
+ * @ingroup cfg_constants
+ *      This defines classifier type to be Class L4 TBD
  */
 #define NETCP_CFG_CLASS_TYPE_L4  0
 
 /**
  * @def NETCP_CFG_CLASS_TYPE_L3_L4
- *      This defines classifier type to be Class L4 and L3
+ * @ingroup cfg_constants
+ *      This defines classifier type to be Class L4/L3 TBD
  */
 #define NETCP_CFG_CLASS_TYPE_L3_L4  1
+
      union
     {
         NETCP_CFG_CLASS_L3_L4_T     c_l3_l4;    /**< @ref NETCP_CFG_CLASS_L3_L4_T */
@@ -474,7 +531,7 @@ typedef struct NETCP_CFG_CLASSIFIER_Tag
 
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief netcp_cfgAddClass   API can be used to route a packet flow to a specific PKTIO channel
  * 
  *  @details This api can be used to route a packet flow to a particular PktIO channel, use a specific
@@ -495,7 +552,7 @@ typedef struct NETCP_CFG_CLASSIFIER_Tag
 
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief netcp_cfgDelClass   API can be used to delete a preconfigured classifier
  * 
  *  @details This API can be used to delete a preconfigured classifier
@@ -526,7 +583,7 @@ typedef void (*NETCP_CFG_STATS_CB)(NETAPI_T h,
                                    paSysStats_t* pPaStats);
 
 /**
- *  @ingroup netapi_cfg_functions
+ *  @ingroup cfg_functions
  *  @brief netcp_cfgReqStats   API to request statistics from NETCP
  * 
  *  @details This api is used to request a statistics from NETCP.  This will generate a stats request