addded some comments for doxygen

diff --git a/ti/runtime/netapi/netapi_sec.h b/ti/runtime/netapi/netapi_sec.h
index 68b8e07a68517239e5f8265c38b1b74e540e9c2e..7bfc3712691100e9c19e171eeb606f8773516cea 100755 (executable)
--- a/ti/runtime/netapi/netapi_sec.h
+++ b/ti/runtime/netapi/netapi_sec.h
@@ -60,7 +60,7 @@
  *  @ingroup netapi_structures
  *  @brief NETAPI SA Statistics
  *
- *  @details Pointer to this strucutre is passed in the call to netapi_getSaStats API.
+ *  @details Pointer to this strucutre is passed in the call to netapi_getSaStats API. It will be popluated with the requested statistics.  Currently only IPSEC stats are valid.
  */
 typedef struct NETAPI_SA_STATS_Tag
 {
@@ -76,32 +76,32 @@ typedef struct NETAPI_SA_STATS_Tag
  *  @ingroup netapi_structures
  *  @brief NETAPI security SA information
  *
- *  @details This structure contains SA information 
+ *  @details This structure contains the information necessary to create a security association (for either for inflow mode or sideband mode)
  */
 typedef struct NETAPI_SEC_SA_INFO_tag
 {
     nwal_SaDir          dir;            /**< Direction for the channel. Inbound or Outbound */
     uint32_t            spi;            /**< IPSec Security Parameter index */
     nwal_IpSecProto     proto;          /**< IpSec Proto (ESP/AH) */
-    nwal_saMode         saMode;         /**< Tunnel/ Transport mode */
-    nwal_IpType         ipType;         /**< IPV4 or V6 */
-    nwalIpAddr_t        src;            /**< Source IP Address (remote) */
-    nwalIpAddr_t        dst;            /**< DST IP Address (local) */
-    uint32_t            replayWindow;   /**< Replay Window Size */
+    nwal_saMode         saMode;         /**< Tunnel/ Transport mode (sideband RX/TX) */
+    nwal_IpType         ipType;         /**< IPV4 or V6 (sideband RX/TX) */
+    nwalIpAddr_t        src;            /**< Source IP Address (remote) (sideband RX) */
+    nwalIpAddr_t        dst;            /**< DST IP Address (local) (sideband RX) */
+    uint32_t            replayWindow;   /**< Replay Window Size (sideband RX) */
     nwal_saAALG         authMode;       /**< Authentication Algorithm */
     nwal_saEALG         cipherMode;     /**< Encryption Algorithm */
-    uint32_t            esnLo;          /**< Initial Value of Extended Sequence Number LSB */
-    uint32_t            esnHi;          /**< Initial Value of Extended Sequence Number MSB */
+    uint32_t            esnLo;          /**< Initial Value of Extended Sequence Number LSB (sideband TX) */
+    uint32_t            esnHi;          /**< Initial Value of Extended Sequence Number MSB (sideband TX) */
 } NETAPI_SEC_SA_INFO_T;
 
 
 /**
- * @brief This defines the SA mode of operation to be INFLOW
+ * @brief This defines the SA mode of operation to be INFLOW.  This means that IPSEC will be applied as the packet is being received or just before it is transmitted
  */
 #define NETAPI_SEC_SA_INFLOW   0x2
 
 /**
- * @brief This defines the SA mode of operation to be SIDEBAND
+ * @brief This defines the SA mode of operation to be SIDEBAND.  This means that Security Acclerator is to be used a traditional accelerator.
  */
 #define NETAPI_SEC_SA_SIDEBAND 0x1
 
@@ -111,17 +111,17 @@ typedef struct NETAPI_SEC_SA_INFO_tag
  *
  *  @details API to configure an IPSec SA. SAs are IPSec security contexts and define a uni-directional
  *           secure path (tunnel or transport). SAs are attached to MAC interfaces that have already
- *           been created. API allows SA to be configured as either inflow or sideband mode
+ *           been created. API allows SA to be configured as either inflow or sideband mode. This API is used for both receive and transmit SAs.
  *  @param[in]  h            The NETAPI handle, @ref NETAPI_T
  *  @param[in]  iface_no     Interface to attach SA to.
  *  @param[in]  sa_info      Information on the SA being added, @ref NETAPI_SEC_SA_INFO_T
  *  @param[in]  key_params   Security key information for the SA.
  *  @param[in]  mode         SA implementation mode @ref NETAPI_SEC_SA_SIDEBAND or @ref NETAPI_SEC_SA_INFLOW
  *  @param[in]  route        @ref NETCP_CFG_ROUTE_HANDLE_T
- *  @param[in]  data_mode_handle     Returned data mode handle for PKTIO
- *  @param[in]  inflow_mode_handle   Returned inflow mode handle for PKTIO
+ *  @param[in]  data_mode_handle     Returned data mode handle for PKTIO (in the case of sideband SAs)
+ *  @param[in]  inflow_mode_handle   Returned inflow mode handle for PKTIO (in the case of TX inflow SAs)
  *  @param[out]  perr        Pointer to error code.
- *  @retval     Aplication id associated with created SA @ref NETCP_CFG_SA_T
+ *  @retval     Application id associated with created SA @ref NETCP_CFG_SA_T. This ID is used when referencing this SA in subsequent APIs (eg. to delete it). Also in the case of Receive Inflow,  packets will be tagged with this ID so that s/w will know that the packet has already been decrypted, authenticated and window-replay checked. (note: if a RX policy is matched also then the ID associated with the policy will be tagged instead).
  *  @pre        @ref netapi_init
  */
 NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T h,
@@ -154,14 +154,14 @@ void netapi_secDelSA(NETAPI_T h,int iface_no, NETCP_CFG_SA_T  sa_app_id,  int *p
  *
  *  @details API to add a recieve security policy
  *  @param[in]  h       The NETAPI handle @ref NETAPI_T
- *  @param[in] sa       Application id returned from call to @ref netapi_secAddSA
+ *  @param[in] sa       Application id returned from call to @ref netapi_secAddSA.  This SA must have beeen configured for (a) RX and (b) Inflow mode.
  *  @param[in] ipType   IPV4 or IPV6
- *  @param[in] src_ip_addr
- *  @param[in] dst_ip_addr
- *  @param[in] ip_qualifiers
+ *  @param[in] src_ip_addr  source IP for policy check
+ *  @param[in] dst_ip_addr  destination IP for policy check
+ *  @param[in] ip_qualifiers  IP qualifiers for policy check (see @ref  nwaIpOpt_t)
  *  @param[in] route    Optional route @ref NETCP_CFG_ROUTE_HANDLE_T
  *  @param[out] perr    Pointer to error code.
- *  @retval    Aplication id associated with created receive security policy @ref NETCP_CFG_IPSEC_POLICY_T
+ *  @retval    Aplication id associated with created receive security policy @ref NETCP_CFG_IPSEC_POLICY_T.  This is used to refer to the policy in the @ref netapi_secDelRxPolicy call.  Also, packets that match this policy but do not pass any further lookups in NETCP will be tagged with this ID
  *  @pre        @ref netapi_init @ref netapi_secAddSA
 */
 NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T h,