more dox
authorDavid Lide <a0216552@gtudci01.(none)>
Wed, 31 Oct 2012 20:04:29 +0000 (16:04 -0400)
committerDavid Lide <a0216552@gtudci01.(none)>
Wed, 31 Oct 2012 20:04:29 +0000 (16:04 -0400)
ti/runtime/netapi/netapi.h
ti/runtime/netapi/netcp_cfg.h
ti/runtime/netapi/pktio.h

index 56f814ab7c2e7268a9474b907414cf8efdca07a0..05b8d006875e709d131a75e74e34a28eebbcd428 100755 (executable)
@@ -263,13 +263,13 @@ void netapi_shutdown(NETAPI_T  p);
  *  @ingroup netapi_gen_functions
  *  @brief netapi_getPktlibIfTable  API returns a Pktlib_HeapIfTable to use when creating pktlib heaps
  *
- *  @details Application will need a heapIfTable in order to create its own heaps. This
+ *  @details Application will need a Pktlib_HeapIfTable in order to create its own heaps. This
  *           function returns a table that can be passed in the call to Pktlib_CreateHeap
  *           The memory used for these heaps is  special with the following characteristics: 
  *             - Specific alignment.
  *             - Must be contguous.
  *             - Must have a physical to virtual mapping that  is known by NETAPI. 
- *           Thus it must be completely managed by NETAPI. This interfaced table provides a
+ *           Thus it must be completely managed by NETAPI. This interface table provides a
  *           malloc function that the pktlib heap library uses to allocate data for the heap
  *           buffers.
  *  @retval     Pktlib_HeapIfTable pointer 
@@ -372,7 +372,7 @@ static inline void netapi_setCookie(NETAPI_T p, void * cookie)
  *  @ingroup netapi_gen_functions
  *  @brief netapi_netcpPoll  API is used to poll for NETCP configuration response messages.
  *
- *  @details Application, if controlling the scheduler,  will need to call this
+ *  @details Application, if implementing the scheduler,  will need to call this
  *           function periodically to check for NETCP configuration responses (eg
  *           statistics requests). 
  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
@@ -408,7 +408,7 @@ return -1;  //no room
 /**
  *  @ingroup netapi_gen_functions
  *  @brief netapi_unregisterHeap  API is used to un-register a heap that was created by application 
- *                                and previously registerd so that it's garbage queue could  be polled 
+ *                                and previously registered so that it's garbage queue could  be polled 
  *                                automatically by @ref netapi_poll_heapGarbage(). 
  *
  *  @details This API un-registers an application-created heap with the netapi instance. 
@@ -433,7 +433,7 @@ return -1;  //not found
  *  @ingroup netapi_gen_functions
  *  @brief netapi_closeHeap  API is used to remove a created pktlib heap
  *
- *  @details This API removes anapplication-created heap with the netapi instance
+ *  @details This API removes an application-created heap with the netapi instance
  *           NOTE: descriptors are zapped and cannot be reused]
  *  @param[in]  p   The NETAPI handle, @ref NETAPI_T
  *  @param[in]  h :  handle to pklib heap 
index 33e5248f60fff0a73e26b51a169bf9d775434540..84bc14ff052ff8222b512c1446dbe709113e9d36 100755 (executable)
@@ -116,14 +116,14 @@ Cppi_HostDesc->origBuffPtr
 
 /**
  * @ingroup cfg_constants
- * @brief  This defines the handle to NETCP configuration flow.
+ * @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.
  */
 typedef void *  NETCP_CFG_FLOW_HANDLE_T;
 
 /**
  * @ingroup cfg_constants
  * @def NETCP_DEFAULT_FLOW
- * @brief This defines the default FLOW. If the default flow is used, NETCP will use the default @pktlib heap created by @netapi_init 
+ * @brief This defines the default FLOW for NETCP to use. 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.
  */
 #define NETCP_DEFAULT_FLOW  (NETCP_CFG_FLOW_HANDLE_T*) NULL
 
@@ -176,20 +176,20 @@ typedef struct NETCP_CFG_ROUTE_Tag
 
 /**
  * @ingroup cfg_constants
- * @brief  Handle to the default NETCP route.
- * @details Application to use this handle to identify default NETCP route.
+ * @brief  Handle to NETCP VLAN configuration (FUTURE).
+ * @details Application to use this handle to identify a VLAN configutation.
  */
 typedef void * NETCP_CFG_VLAN_T;
 
 /**
  * @ingroup cfg_constants
- * @brief  AppID for MAC interface
+ * @brief  AppID for packets matching a  MAC interface rule
  */
 typedef uint32_t NETCP_CFG_MACIF_T;
 
 /**
  * @ingroup cfg_constants
- * @brief AppID for IP interface
+ * @brief AppID for packets matching an IP interface rule
  */
 typedef uint32_t NETCP_CFG_IP_T;
 
@@ -197,14 +197,14 @@ typedef uint32_t NETCP_CFG_IP_T;
 
 /**
  * @ingroup cfg_constants
- * @brief This define is used to identify the application id associated with a created SA
+ * @brief This define is used to identify the application id associated with a created SA (IPSEC security association) rule
  */
 typedef uint32_t NETCP_CFG_SA_T;
 
 
 /**
  * @ingroup cfg_constants
- * @brief AppId used to identify NETCP IPSEC policy
+ * @brief AppId for packets matching an NETCP IPSEC policy rule
  */
 typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 
@@ -212,15 +212,15 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 /**
  * @ingroup cfg_constants
  * @def NETCP_CFG_NO_INTERFACE
- *      This define is to be used in AddIp, AddClassifier to indicate any MAC address.
+ *      This define is to be used in AddIp, AddClassifier, addSA, etc. to indicate that the rule can be bound to any MAC address.
  */
 #define NETCP_CFG_NO_INTERFACE 0xff
 
 
 
 /**
- * @note  APPIDs are present in RX packet meta data and tell "how far the packet got
- * through the classification rules of NETCP 
+ * @note  APPIDs are present in RX packet meta data and tell "how far" the packet got
+ * through the classification rules of NETCP. 
  * APPID is 32 bits:
  * bits 31-24 = MATCH STAGE (NETAPI_NECP_MATCH_xxx below)
  * bits 23-8  = identifier (depends on match stage)
@@ -230,7 +230,7 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 /**
  * @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 for an APPID that indicates that a packet 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
@@ -238,8 +238,8 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 /**
  * @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
+ *      This define is used for an APPID that indicates that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID. 
+ *      Packet also matched a generic IP rule attached to that interface.  The IP rule # for the interface
  *      is given in Bytes 3,2 of the APPID.   Packet did not match any other rule
  */
 #define NETAPI_NETCP_MATCH_GENERIC_IP   0x20000000  //lower byte==interface
@@ -248,8 +248,8 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 /**
  * @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
+ *      This define is used for an APPID that indicates that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.
+ *      Packet also matched a generic IP rule  attached to that interface OR a general IP rule added as part of
  *      the classifier or it matched a combination of ISPEC SA rule and a policy check.  Finally,
  *      Packet matched a L4 port rule that was added as part of a classifer.  Bytes 3-2
  *      give the ID of the classifier . Packet did not match any other rule
@@ -259,8 +259,8 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 /**
  * @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
+ *      This define is used for an APPID that indicates that a  packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.
+ *      Packet also  matched a general IP rule added as part of a classifier.  But it not match a
  *      L4 port or any other rule. We cannout say what classifer partially matched so Bytes 3-2 are
  *      not applicable
  */
@@ -269,8 +269,8 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 /**
  * @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
+ *      This define is used for an APPID that indicates that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.
+ *      Packet also matched an IPSEC SA  rule (matched proto, dest ip and SPI).  The SA id  is in
  *      bytes 3-2 of APPID.  Packet did not match any other rule (so may have failed a policy check)
  */
 #define NETAPI_NETCP_MATCH_IPSEC        0x01000000  //lower byte==interface, Or' in SA id (16 bits)
@@ -278,8 +278,8 @@ typedef uint32_t NETCP_CFG_IPSEC_POLICY_T;
 /**
  * @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
+ *      This define is used for an APPID that indicates that a packet matched a MAC entry.  Entry # (logical interface) is in byte 0 of APPID.
+ *      Packet also matched an IPSEC SA rule (matched proto, dest ip and SPI).  Packet also matched
  *      a POLICY RULE - this is a check of the inner IP.  The IPSEC RX Policy ID  is in
  *      bytes 3-2 of APPID.  Packet did not match any other rule 
  */
@@ -343,7 +343,7 @@ void netcp_cfgDelMac(NETAPI_T h,int iface_no,  int *err);
 
 /**
  *  @ingroup cfg_functions
- *  @brief  API attaches an IP adderess and qualifier to a MAC interface
+ *  @brief  API attaches an IP address and qualifier to a MAC interface
  * 
  *  @details This api is used to add an IP address to a MAC interface along
  *            with optional IP qualifier. A route, @ref NETCP_CFG_ROUTE_HANDLE_T,or NULL for default 
@@ -442,14 +442,14 @@ typedef uint32_t NETCP_CFG_CLASS_T;
  *  @ingroup cfg_structures
  *  @brief NETAPI Class L4 Configuration
  *
- *  @details This structure contains Class L4 Configuration. L2,L3 implied by iface, ip.  L4 packet is defined by the protocol and ports
+ *  @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)
  */
 typedef struct NETCP_CFG_CLASS_L4_Tag
 {
-    int             iface;      /**< Indicates which MAC interface packet is from */
-    NETCP_CFG_IP_T  ip;         /**< @ref NETCP_CFG_IP_T */
+    int             iface;      /**< Indicates which MAC interface packet should be received on*/
+    NETCP_CFG_IP_T  ip;         /**< IP rule to match: see @ref NETCP_CFG_IP_T */
     nwal_appProtoType_t proto;   /**< L4 proto (-1 for don't care)*/
-    nwalAppProto_t   appProto;   /**< Ports or equivalent */
+    nwalAppProto_t   appProto;   /**< L4 Ports or equivalent */
 
 } NETCP_CFG_CLASS_L4_T;
 
@@ -458,15 +458,15 @@ typedef struct NETCP_CFG_CLASS_L4_Tag
  *  @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; inner IP implied by the policy configuration
+ *  @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. 
  */
 //classifier L4 + policy  (L2, L3 (outer), tunnel, L3 (inner)  implied by policy
 typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
 {
-    int             iface;      /**< Indicates which MAC interface packet is from */
-    NETCP_CFG_IPSEC_POLICY_T  ip_policy; /**< IPSEC policy configuration */
+    int             iface;      /**< Indicates which MAC interface packet should be received from */
+    NETCP_CFG_IPSEC_POLICY_T  ip_policy; /**< IPSEC policy configuration. see @ref NETCP_CFG_IPSEC_POLICY_T */
     nwal_appProtoType_t proto;   /**< L4 proto (-1 for don't care)*/
-    nwalAppProto_t   appProto;   /**< Ports or equivalent */
+    nwalAppProto_t   appProto;   /**< L4 Ports or equivalent */
 
 } NETCP_CFG_CLASS_L4_IPSEC_T;
 
@@ -477,17 +477,17 @@ typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
  *  @ingroup cfg_structures
  *  @brief NETAPI Classifier L4/L3 configuration
  *
- *  @details This structure contains Class L4 and Class L3 configuration. L2 implied by iface
+ *  @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.
  */
 typedef struct NETCP_CFG_CLASS_L3_L4_Tag
 {
     int             iface;      /**< Indicates which MAC interface packet is from */
     nwal_IpType ipType;         /**< IP address type, IPV4 or IPV6 */
-    nwalIpAddr_t  * ip_addr;    /**< IP addres */
+    nwalIpAddr_t  * ip_addr;    /**< IP address to match */
     nwalIpOpt_t * ip_qualifiers;/**< IP address qualifiers */
     NETCP_CFG_ROUTE_HANDLE_T p_fail_route; /**< What to do if L3 matches but L4 fails AND L3 is a 
                                             * new rule.(if exisitng rule, then existing fail
-                                            *route will be used. */
+                                            *route will be usedi). */
     nwal_appProtoType_t proto;   /**< L4 proto (-1 for don't care)*/
     nwalAppProto_t   appProto;   /**< Ports or equivalent */
 } NETCP_CFG_CLASS_L3_L4_T;
@@ -504,7 +504,7 @@ typedef struct NETCP_CFG_CLASSIFIER_Tag
 /**
  * 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
+ *      @ref NETCP_CFG_CLASS_TYPE_L4 , @ref NETCP_CFG_CLASS_TYPE_L3_L4, _
  */
     int classType;
 
index 857899d47ec0f94b1ae07ae11d723cb481621bba..1e120eeb3cad4af56ce8595235c877a8b0902719 100755 (executable)
@@ -89,7 +89,7 @@
 /**
  * @def NETCP_SB_TX
  * @ingroup pktio_constants
- * @brief      This defines the pktio NETCP-SA transmit SIDEBAND channel name. This channle is used to send pacekts to sideband crypto
+ * @brief      This defines the pktio NETCP-SA transmit SIDEBAND channel name. This channle is used to send packets to sideband crypto
  */
 #define NETCP_SB_TX "NETCP_SB_TX"