updates of header file documentation
authorDavid Lide <a0216552@gtudci01.(none)>
Wed, 31 Oct 2012 14:18:01 +0000 (10:18 -0400)
committerDavid Lide <a0216552@gtudci01.(none)>
Wed, 31 Oct 2012 14:18:01 +0000 (10:18 -0400)
ti/runtime/netapi/netapi_sched.h
ti/runtime/netapi/netapi_sec.h
ti/runtime/netapi/netapi_tune.h
ti/runtime/netapi/netcp_cfg.h
ti/runtime/netapi/pktio.h

index 4318ee4667fba6bd60c7782f499afc54cb47e8be..c01ec9ad37390cfe7dfce6b533065336629b19c3 100755 (executable)
 #include "netapi.h"
 
 /**
- * @brief This define the handle to the NETAPI scheduling context TBD
+ * @brief This define the handle to the NETAPI scheduling context.  Each transport application thread should have its own scheduler context.
  */
 struct  NETAPI_SCHED_HANDLE_Tag;
 
 
 /**
  *  @ingroup netapi_cb_functions
- *  @brief NETAPI_SCHED_CB   Callback function for scheduling context hous keeping. TBD
+ *  @brief NETAPI_SCHED_CB   Callback function for scheduling context hous keeping.  This allows application to set a function to be periodically called by scheduler to perform house keeping chores. If NULL, then no callback will be invoked
  * 
- *  @details The application provides a callback function that NETAPI scheduling context to retrieve TBD
+ *  @details The application provides a callback function that NETAPI scheduling context  will call on  a periodic/ low priority basis.
  *  @param[in]  h   The handle to the NETAPI scheduling context
  *  @retval     none 
  *  @pre       @ref netapi_init
@@ -88,28 +88,27 @@ typedef struct NETAPI_SCHED_CONFIG_Tag
 /**
  * @def NETAPI_SCHED_DURATION
  * @ingroup sched_constants
- *      This defines the duration option  of scheduler context being configured TBD
  */
 #define NETAPI_SCHED_DURATION 0x1
 
 /**
  * @def NETAPI_SCHED_POWER
  * @ingroup sched_constants
- *      This defines the Power option  of scheduler context being configured. TBD
+ *      This defines the Power option  of scheduler context being configured.  FUTURE
  */
 #define NETAPI_SCHED_POWER 0x2
 
 /**
  * @def NETAPI_SCHED_FINE
  * @ingroup sched_constants
- *      This defines the fine tune option of scheduler context being configured. TBD
+ *      This defines the fine tune option of scheduler context being configured. FUTURE
  */
 #define NETAPI_SCHED_FINE  0x4
 
 /**
  * @def NETAPI_SCHED_CBV
  * @ingroup sched_constants
- *      This defines the call back option of scheduler context being configured. TBD.
+ *      This defines that the housekeeping   call back option of scheduler context has been configured.
  */
 #define NETAPI_SCHED_CBV  0x8
 
@@ -140,18 +139,18 @@ typedef struct NETAPI_SCHED_CONFIG_Tag
 /**
  * @def NETAPI_SCHED_POWER_ALWAYS_OFF
  * @ingroup sched_constants
- *      This define is used to configure scheduler power_control option to be always off TBD
+ *      This define is used to configure scheduler power_control option to be always off  FUTURE
  */
 #define NETAPI_SCHED_POWER_ALWAYS_OFF 0
 
 /**
  * @def NETAPI_SCHED_POWER_ALWAYS_ON
  * @ingroup sched_constants
- *      This define is used to configure scheduler power_control option to be always on
+ *      This define is used to configure scheduler power_control option to be always on FUTURE
  */
 #define NETAPI_SCHED_POWER_ALWAYS_ON 100
 
-    int idle_time;                          /**< idle time TBD */
+    int idle_time;                          /**< idle time  */
 } NETAPI_SCHED_CONFIG_T;
 
 
@@ -175,28 +174,28 @@ typedef struct NETAPI_SCHED_HANDLE_Tag
 /**
  * @def NETAPI_SCHED_STATE_CLOSE
  * @ingroup sched_constants
- *      This define indicates the state of the scheduler to be CLOSE (idle) state TBD
+ *      This define indicates the state of the scheduler to be CLOSE (idle) state
  */
 #define NETAPI_SCHED_STATE_CLOSE 0
 
 /**
  * @def NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS
  * @ingroup sched_constants
- *      This define indicates the state of the scheduler is being shutdown state TBD
+ *      This define indicates the state of the scheduler is being shutdown state
  */
 #define NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS 1
 
 /**
  * @def NETAPI_SCHED_STATE_OPEN
  * @ingroup sched_constants
- *      This define indicates the state of the scheduler is OPEN (running) TBD
+ *      This define indicates the state of the scheduler is OPEN (running)
  */
 #define NETAPI_SCHED_STATE_OPEN 2
 
     void * back;                        /**< Pointer back to NETAPI  handle */
     NETAPI_SCHED_CONFIG_T config;       /**< NETAPI scheduler configuration */
-    uint64_t start;                     /**< Start time of NETAPI scheduler context TBD*/ 
-    volatile int shutdown_reason;       /**< FUTURE-not implemented TBD */
+    uint64_t start;                     /**< Start time of NETAPI scheduler context */ 
+    volatile int shutdown_reason;       /**< FUTURE-not implemented  */
     volatile uint64_t shutdown_time;    /**< Time till scheduler context will be shutdown/closed */
 
 } NETAPI_SCHED_HANDLE_T;
@@ -205,7 +204,7 @@ typedef struct NETAPI_SCHED_HANDLE_Tag
 
 
 /// @cond FUTURE
-/* return codes for wait_for_events() TBD, currently not used*/
+/* return codes for wait_for_events()  currently not used*/
 #define NETAPI_SCHED_RETURN_ERR         0       /**<unknown, err */
 #define NETAPI_SCHED_RETURN_TO          1       /**<returned after timeout */
 #define NETAPI_SCHED_RETURN_SHUTDOWN    2       /**<returned after shutdown */
@@ -238,7 +237,7 @@ typedef struct NETAPI_SCHED_SHUTDOWN_Tag
 /**
  * @def NETAPI_SCHED_SHUTDOWN_TO
  * @ingroup sched_constants
- *      This define is used to shudown the scheduling context TBD
+ *      This define is used to shudown the scheduling context after a short while. FUTURE 
  */
 #define NETAPI_SCHED_SHUTDOWN_TO  1
 
@@ -291,7 +290,7 @@ int netapi_schedControl(NETAPI_SCHED_HANDLE_T *s,
  *  @details API for main entry point to scheduler. User application gives up control to scheduler.
   *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
  *  @param[out] p_err: error code, zero on sucess, non-zero on failure
- *  @retval     TBD
+ *  @retval     always 1
  *  @pre        @ref netapi_schedOpen 
  */
 int netapi_schedWaitForEvents(NETAPI_SCHED_HANDLE_T *s,
@@ -305,7 +304,7 @@ int netapi_schedWaitForEvents(NETAPI_SCHED_HANDLE_T *s,
  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
  *  @param[in]  p_close  @ref NETAPI_SCHED_SHUTDOWN_T
  *  @param[out] p_err    Pointer to error code.
- *  @retval     TBD
+ *  @retval     NO USED, ALWAYS 1
  *  @pre        @ref netapi_schedOpen 
  */
 int netapi_schedShutdown(NETAPI_SCHED_HANDLE_T * s, 
@@ -330,12 +329,12 @@ static NETAPI_T netapi_schedGetNetapiHandle(NETAPI_SCHED_HANDLE_T *s)
 
 /**
  *  @ingroup sched_functions
- *  @brief netapi_sched_get_stats: API to tget NETAP scheduling context statistics
+ *  @brief netapi_sched_get_stats: API to get NETAP scheduling context statistics
  *
  *  @details   API to tget NETAP scheduling context statistics
- *  @param[in]  p_pkts TBD
- *  @param[in]  p_cycles TBD
- *  @param[in]  p_ccycles TBD
+ *  @param[in]  p_pkts  total number of packets processed by scheduler poll loop
+ *  @param[in]  p_cycles total number cycles taken by scheduler poll loop
+ *  @param[in]  p_ccycles  total number of cache control cycles taken by scheduler poll loop
  *  @retval     none
  */
 void netapi_sched_get_stats(unsigned long long * p_pkts, 
index eebd52deb20801e79ce449b7cdf610a713391756..525b89e09986fde0e9c2957bdaf8f36991306470 100755 (executable)
@@ -117,13 +117,13 @@ typedef struct NETAPI_SEC_SA_INFO_tag
 
 
 /**
- * @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 TBD
+ * @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. This is a more efficient way to use SA and saves host cycles.
  * @ingroup security_constants
  */
 #define NETAPI_SEC_SA_INFLOW   0x2
 
 /**
- * @brief This defines the SA mode of operation to be SIDEBAND.  This means that Security Acclerator is to be used a traditional accelerator TBD
+ * @brief This defines the SA mode of operation to be SIDEBAND.  This means that Security Acclerator is to be used a traditional accelerator where for RX, the packet will first be received on host and then sent back to SA for crypto.  For TX the packet will first be sent to SA for crypto, returned to host and then sent to NETCP for transmit.
  * @ingroup security_constants
  */
 #define NETAPI_SEC_SA_SIDEBAND 0x1
index 7a80a9ae728399b95c7a925798ccbff04c37bab2..d341dce1b9d0b78983015edaecfaf6c922d4ad24 100755 (executable)
 /**
  * @ingroup tune_parameters
  * @def TUNE_NETAPI_MAX_NUM_L2_L3_HDRS
- *      This defines the number maximum number of L2_L3 headers TBD
+ *      This defines the number maximum number of L2_L3 headers to reserve  in the nwal layer. This should be kept small as transport lib does not expose this inwal feature by default
  */
 #define TUNE_NETAPI_MAX_NUM_L2_L3_HDRS         3
 
 /**
  * @ingroup tune_parameters
  * @def TUNE_NETAPI_MAX_NUM_TRANS
- *      This defines the number maximum number of trans TBD
+ *      This defines the number maximum number of transactions with NETCP that can be outstanding at any one time 
  */
 #define TUNE_NETAPI_MAX_NUM_TRANS              (TUNE_NETAPI_MAX_NUM_MAC + TUNE_NETAPI_MAX_NUM_IP + TUNE_NETAPI_MAX_NUM_PORTS + TUNE_NETAPI_MAX_NUM_IPSEC_CHANNELS)
 
 /**
  * @ingroup tune_parameters
  * @def  TUNE_NETAPI_MAX_BUF_POOLS_IN_FLOW
- *      This defines the  maximum number of buffer pools in flow -TBD
- * @note This define should NOT be changes
+ *      This defines the  maximum number of buffer pools in flow - A flow is used by hw when it needs a buffer for a receive packet.  This define allows the maximum number of pools (free descriptor queues) to be defined for a flow, so that different sized packets can be allocated from different memory areas.
+ * @note This define should NOT be changed as HW assumes at most 4 now
  */
 #define TUNE_NETAPI_MAX_BUF_POOLS_IN_FLOW  4  //!!do not change!!
 
index 672d2b486b66010c4ead5000f8b9499a6284f0ad..33e5248f60fff0a73e26b51a169bf9d775434540 100755 (executable)
@@ -58,6 +58,7 @@
 /**
  *  @ingroup cfg_structures
  *  @brief CPPI flow ID for default case, use NETCP_DEFAULT_FLOW
+ *  @details A flow defines a set of free queues (@pktlib heap) for h/w to use to get free packet descriptor(s) and buffer(s) to use when receiving a packet
  */
 typedef struct NETCP_CFG_FLOW_Tag
 {
@@ -122,21 +123,21 @@ typedef void *  NETCP_CFG_FLOW_HANDLE_T;
 /**
  * @ingroup cfg_constants
  * @def NETCP_DEFAULT_FLOW
- *      This defines the NETCP default FLOW to be NULL.
+ * @brief This defines the default FLOW. If the default flow is used, NETCP will use the default @pktlib heap created by @netapi_init 
  */
 #define NETCP_DEFAULT_FLOW  (NETCP_CFG_FLOW_HANDLE_T*) NULL
 
 
 /**
  * @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 route.
+ * @details Application to use this handle to identify a  NETCP route.  A NETCP route defines the pktio channel for packets received by NETCP and the flow to use
  */
 typedef void * NETCP_CFG_ROUTE_HANDLE_T;
 
 /**
  * @def NETCP_DEFAULT_ROUTE
- *      This defines the NETCP default ROUTE to be NULL.
+ *      This defines the NETCP default route.  This route has NETCP send received packets to the default NETCP pktio channel using descriptors and buffers from the default flow. The default route is created by @netapi_init
  */
 #define NETCP_DEFAULT_ROUTE  (NETCP_CFG_ROUTE_HANDLE_T*) NULL
 
@@ -144,6 +145,7 @@ typedef void * NETCP_CFG_ROUTE_HANDLE_T;
 /**
  *  @ingroup cfg_structures
  *  @brief NETCP application defined route information.
+ *  @details This structure is used to define a packet receive route.  A route consists of a flow where to get free descriptors and buffers to hold the packet, and a destination queue where to place the packet.
  *
  */
 typedef struct NETCP_CFG_ROUTE_Tag
@@ -313,7 +315,7 @@ NETCP_CFG_FLOW_HANDLE_T netcp_cfgAddFlow(NETAPI_T h,
  *  @ingroup cfg_functions
  *  @brief netcp_cfgDelFlow   API to delete a flow
  * 
- *  @details This api is used to delete a flow
+ *  @details This api is used to delete a flow previousy added.
  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
  *  @param[in]  p    handle to NETCP  flow
  *  @param[out] err     pointer to error return
@@ -355,7 +357,7 @@ void netcp_cfgDelMac(NETAPI_T h,int iface_no,  int *err);
  *  @param[in]  ip_addr      ip_address
  *  @param[in]  ip_qualifiers   ip_qualifiers (all 0 for no qualifiers). This can be used to apply special handling for
  *                  diffserv category for example.
- *  @param[in]  route   [future] handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
+ *  @param[in]  route       handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
  *  @param[out] err     pointer to error return
  *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
  *  @pre       @ref netapi_init
@@ -404,13 +406,13 @@ void netcp_cfgDelIp(NETAPI_T h, int iface_no,  nwal_IpType ipType,
  *      MAC matching supplied argument and not matching any other lookup entry (see @ref netcp_cfgAddIp) to
  *      the supplied route, @ref NETCP_CFG_ROUTE_T, (or default route).
  *      Packets arriving that match this rule are identified in meta data with Appid=  NETAPI_NETCP_MATCH_GENERIC_MAC
- *      Note: The internal SOC switch must be "taught" that this mac
+ *      Note: The internal SOC switch (if operating in full swithc mode) may need to  be "taught" that this mac
  *      address is present by transmitting a packet with destination mac = this interface mac address.
  *  @param[in]  h   NETAPI instance handle, @ref NETAPI_T
  *  @param[in]  p_mac   pointer to 6 byte MAC address for interface
  *  @param[in]  iface_no    interface number (0,1,..) 
- *  @param[in]  switch_port     (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported] 
- *  @param[in]  route   [future] handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
+ *  @param[in]  switch_port     (0 don't care, 1 switch port 1, 1 switch port 2) [only 0 supported currenly
+ *  @param[in]  route   handle of a created route or NULL to use internal default route, @ref NETCP_CFG_ROUTE_HANDLE_T
  *  @param[in]  vlan    [future[ vlan configuration . Set to NULL, @ref NETCP_CFG_VLAN_T
  *  @param[in]  state   [future] interface state (0=down, 1= up)
  *  @param[out] err     pointer to error return
@@ -440,7 +442,7 @@ 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
+ *  @details This structure contains Class L4 Configuration. L2,L3 implied by iface, ip.  L4 packet is defined by the protocol and ports
  */
 typedef struct NETCP_CFG_CLASS_L4_Tag
 {
@@ -456,7 +458,7 @@ 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
+ *  @details This structure contains Class L4 plus IPSEC policy configuration. L2,L3 implied by iface, ip; inner IP implied by the policy configuration
  */
 //classifier L4 + policy  (L2, L3 (outer), tunnel, L3 (inner)  implied by policy
 typedef struct NETCP_CFG_CLASS_L4_IPSEC_Tag
@@ -494,7 +496,7 @@ typedef struct NETCP_CFG_CLASS_L3_L4_Tag
  *  @ingroup cfg_structures
  *  @brief NETAPI Classifier configuration
  *
- *  @details This structure contains the NETAPI classifer configuration
+ *  @details This structure contains the NETAPI classifer configuration.  This is a union of the different classifier types above
  */
 typedef struct NETCP_CFG_CLASSIFIER_Tag
 {
@@ -509,14 +511,13 @@ typedef struct NETCP_CFG_CLASSIFIER_Tag
 /**
  * @def NETCP_CFG_CLASS_TYPE_L4
  * @ingroup cfg_constants
- *      This defines classifier type to be Class L4 TBD
- */
+ *      This defines classifier type to be Class L4. Class L4 classifiers specifiy the L4 protocol information of the packets to matched;  the L2,L3 portions of the classifier are implied by supplied handles from the mac interface create and IP Add APIs
 #define NETCP_CFG_CLASS_TYPE_L4  0
 
 /**
  * @def NETCP_CFG_CLASS_TYPE_L3_L4
  * @ingroup cfg_constants
- *      This defines classifier type to be Class L4/L3 TBD
+ *      This defines classifier type to be Class L4/L3 .  Class L3_L4 classifiers specify both the IP address (L3) and the L4 protocol information of the packets to be matched.
  */
 #define NETCP_CFG_CLASS_TYPE_L3_L4  1
 
@@ -532,14 +533,14 @@ typedef struct NETCP_CFG_CLASSIFIER_Tag
 
 /**
  *  @ingroup cfg_functions
- *  @brief netcp_cfgAddClass   API can be used to route a packet flow to a specific PKTIO channel
+ *  @brief netcp_cfgAddClass   API can be used to attach a classifier rule to NETCP.  This can be used to route a particular 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
+ *  @details This api can be used to route a particular packet flow to a particular PktIO channel, using a specific 
  *  pktLib heap, and/or have NetCP attach a tag (classifier id) to the incoming packet.
  *  @param[in]  h    NETAPI instance handle, @ref NETAPI_T
- *  @param[in]  p_class
- *  @param[in]  p_route
- * @param[in]  action
+ *  @param[in]  p_class -> definition of the classifier
+ *  @param[in]  p_route  -> route for packet or default
+ * @param[in]  action -> what to do with packet: one of NETCP_CFG_ACTION_TO_SW, DISCARD or CONTINUE
  *  @param[out] err     pointer to error return
  *  @retval     returned AppID for attached rule. This is returned in RX meta data for packets matching this rule and no other, @ref NETCP_CFG_IP_T
  *  @pre       @ref netapi_init
index 0ddf435b40db006967b7649e4eaf8452cf7ffa13..857899d47ec0f94b1ae07ae11d723cb481621bba 100755 (executable)
 /**
  * @def NETCP_RX
  * @ingroup pktio_constants
- *      This defines the pktio NETCP receive channel name
+ * @brief This defines the default pktio NETCP receive channel name
  */
 #define NETCP_RX "NETCP_RX"
 
 /**
  * @def NETCP_SB_RX
  * @ingroup pktio_constants
- *      This defines the pktio NETCP-SA receive SIDEBAND channel name
+ * @brief This defines the pktio NETCP-SA receive SIDEBAND channel name.  This channel is used to receive the results from sideband crypto operations
  */
 #define NETCP_SB_RX "NETCP_SB_RX"
 
 /**
  * @def NETCP_SB_TX
  * @ingroup pktio_constants
- *      This defines the pktio NETCP-SA transmit SIDEBAND channel name
+ * @brief      This defines the pktio NETCP-SA transmit SIDEBAND channel name. This channle is used to send pacekts to sideband crypto
  */
 #define NETCP_SB_TX "NETCP_SB_TX"
 
  *  @ingroup pktio_structures
  *  @brief PKTIO meta data information .
  *
- *  @details PKTIO meta data information TBD
+ *  @details PKTIO meta data information. meta data is used to convey the results of NETCP pre-processing on receive packets and to tell NETCP what functions to perform on transmitted packets. It is a union of sub-structures (one for TX, one for RX, one for sideband rx, one for sideband tx).
  */
 typedef struct PKTIO_METADATA_Tag
 {
@@ -147,7 +147,7 @@ typedef struct PKTIO_METADATA_Tag
 /**
  * @def PKTIO_META_APP_DEF
  * @ingroup pktio_constants
- *      TBD- is this part of flags2?
+ *      This allows application to define custom packet types.
  */
 #define PKTIO_META_APP_DEF 0x80000000
 
@@ -163,7 +163,8 @@ typedef struct PKTIO_METADATA_Tag
     } u;                                    /**< union NWAL Packet meta data information  */
 
 /**
- * @brief valid for PKTIO_META_TX with IPSEC inflow or PKTIO_PKTIO_META_SB_TX MUST BE nwal_HANDLE_INVALID otherwise
+ * @brief valid for PKTIO_META_TX with IPSEC inflow or PKTIO_PKTIO_META_SB_TX MUST BE nwal_HANDLE_INVALID otherwise.
+ * @details  This is used when crypto is to be preformed on egress packet.
  */
     void * sa_handle;
 } PKTIO_METADATA_T;
@@ -173,9 +174,9 @@ struct PKTIO_HANDLE_tag;
 
 /**
  *  @ingroup pktio_structures
- *  @brief PKTIO polling control struct FUTURE- TBD
+ *  @brief PKTIO polling control struct FUTURE-
  *
- *  @details PKTIO polling control struct FUTURE- TBD
+ *  @details PKTIO polling control struct FUTURE- 
  */
 typedef struct PKTIO_POLL_Tag
 {
@@ -243,7 +244,7 @@ typedef int (*PKTIO_POLL)(struct PKTIO_HANDLE_tag * channel,
                           int * p_err);
 
 /**
- * @brief This defines TBD
+ * @brief This defines an unused packet io channel slot
  */
 #define PKTIO_NA 0
 
@@ -266,21 +267,21 @@ typedef struct PKTIO_CFG_Tag
 /**
  * @def PKTIO_R
  * @ingroup pktio_constants
- *      This defines the pktio channel as type read TBD
+ *      This defines the pktio channel as type read, i.e., for ingress
  */
 #define PKTIO_R 0x1
 
 /**
  * @def PKTIO_W
  * @ingroup pktio_constants
- *      This defines the pktio channel as type write TBD
+ *      This defines the pktio channel as type write, i.e. for egress
  */
 #define PKTIO_W 0x2
 
 /**
  * @def PKTIO_RW
  * @ingroup pktio_constants
- *      This defines the pktio channel as type read/write TBD
+ *      This defines the pktio channel as type read/write 
  */
 #define PKTIO_RW (PKTIO_R | PKTIO_W)
 
@@ -297,14 +298,14 @@ int flags2; /**< Flags for PKTIO channel configuration */
 /**
  * @def PKTIO_GLOBAL
  * @ingroup pktio_constants
- *      This defines the pktio channel as type global TBD
+ *      This defines the pktio channel as type global.  Type global means that this channel can be used by all worker threads/cores
  */
 #define PKTIO_GLOBAL 0x1
 
 /**
  * @def PKTIO_LOCAL
  * @ingroup pktio_constants
- *      This defines the pktio channel as type local TBD
+ *      This defines the pktio channel as type local.  Type local means that thi s channel can only be used by the the thread/core that created it; its name will not be visible to other threads/cores
  */
 #define PKTIO_LOCAL  0x2
 
@@ -325,7 +326,7 @@ int flags2; /**< Flags for PKTIO channel configuration */
 /**
  * @def PKTIO_Q_ANY
  * @ingroup pktio_constants
- *      This defines the pktio IO queue number to be TBD 
+ *      This defines the pktio IO queue number to be specified by the transport library. 
  */
 #define PKTIO_Q_ANY -1
 
@@ -352,16 +353,16 @@ typedef struct PKTIO_HANDLE_Tag
 /**
  * @def PKTIO_INUSE
  * @ingroup pktio_constants
- *      This defines is used to TBD
+ *      This defines whether the pktio channel entry is valid.
  */
 #define PKTIO_INUSE 0xfeedfeed
 
-    int inuse;                      /**<true is pktio channel is in use TBD */
+    int inuse;                      /**<true is pktio channel is in use  */
 
 /**
  * Set the "use_nwal" field to one of the defines listed below.
  * <br>
- * The following defines are used to populate the use_nwal field TBD:
+ * The following defines are used to populate the use_nwal field:
  *      @ref PKTIO_4_IPC , @ref PKTIO_4_ADJ_NWAL, @ref PKTIO_DEF_NWAL. @ref PKTIO_4_ADJ_SB., @ref PKTIO_DEF_SB
  */
     int use_nwal;                  
@@ -369,27 +370,27 @@ typedef struct PKTIO_HANDLE_Tag
 /**
  * @def PKTIO_4_IPC
  * @ingroup pktio_constants
- *      This define is for IPC TBD
+ *      This define is for channels used for IPC between cores
  */
 #define  PKTIO_4_IPC 0
 
 /**
  * @def PKTIO_4_ADJ_NWAL
  * @ingroup pktio_constants
- *      This define is for (RX)app queues managed by NWAL
+ *      This define is for NETCP (RX) channels whose associated queues are managed by NWAL
  */
 #define  PKTIO_4_ADJ_NWAL 1
 
 /**
  * @def PKTIO_DEF_NWAL
  * @ingroup pktio_constants
- *      This define is for default NWAL RX/TX queues
+ *      This define is for NETCP channels that are tied to the default NWAL RX/TX queues
  */
 #define  PKTIO_DEF_NWAL 2
 
 /**
  * @def PKTIO_4_ADJ_SB
- *      This define is for (RX) crypto side band app defined
+ *      This define is for (RX) channels used to get crypto side band results via application managed queues
  * @ingroup pktio_constants
  */
 #define  PKTIO_4_ADJ_SB 3
@@ -397,15 +398,15 @@ typedef struct PKTIO_HANDLE_Tag
 /**
  * @def PKTIO_DEF_SB
  * @ingroup pktio_constants
- *      This define is for crypto side band default
+ *      This define is for channels tied to the default crypto side band  queues
  */
 #define  PKTIO_DEF_SB 4
 
-    struct NETAPI_tag * back;       /**< back handle */
-    void * nwalInstanceHandle;      /**<save here for conveninece  TBD*/
-    PKTIO_CB cb;                    /**< callback for channel */
-    PKTIO_CFG_T cfg;                /**<configuration */
-    Qmss_QueueHnd q;                /**<the associated queue handle */
+    struct NETAPI_tag * back;       /**< back handle  to NETPAI instance */
+    void * nwalInstanceHandle;      /**<save here for conveninece  this is the nwal handle set at init time*/
+    PKTIO_CB cb;                    /**< callback for channel (for Rx) */
+    PKTIO_CFG_T cfg;                /**<configuration  of channel */
+    Qmss_QueueHnd q;                /**<the associated queue handle for channel */
     Qmss_Queue qInfo;               /**<and its qm#/q# */
     int max_n;                      /**<max # of pkts to read in one poll */
     void * cookie;                  /**<app specific */
@@ -417,9 +418,9 @@ typedef struct PKTIO_HANDLE_Tag
 
 /**
  *  @ingroup pktio_structures
- *  @brief PKTIO control TBD
+ *  @brief PKTIO control structure 
  *
- *  @details PKTIO control RBD
+ *  @details PKTIO control stucture for the control API. Allows operations on pktio channel such as CLEAR ,  DIVERT, etc
  */
 typedef struct PKTIO_CONTROL_Tag
 {
@@ -431,12 +432,12 @@ typedef struct PKTIO_CONTROL_Tag
 
 /**
  * @def PKTIO_DIVERT
- *      This defines is used to divert to dest channel TBD
+ *      This defines is used to divert to dest channel 
  */
 #define PKTIO_DIVERT 0x2
 
-    int op;                 /**< TBD */
-    PKTIO_HANDLE_T *dest;   /**< Handle to PKTIO channel */
+    int op;                 /**< control operation (CLEAR, DIVERT, ..) */
+    PKTIO_HANDLE_T *dest;   /**< Handle to PKTIO channel (for DIVERT) */
 } PKTIO_CONTROL_T;