Additional doxygen updates
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi_sched.h
index 52f542e4b57d32077f15b74efa76fdbc7bda2314..4318ee4667fba6bd60c7782f499afc54cb47e8be 100755 (executable)
@@ -68,48 +68,55 @@ struct  NETAPI_SCHED_HANDLE_Tag;
 typedef void (*NETAPI_SCHED_CB)(struct NETAPI_SCHED_HANDLE_Tag *h);
 
 
-
-
-
-
 /**
- *  @ingroup netapi_structures
+ *  @ingroup sched_structures
  *  @brief NETAPI scheduler configuration structure.
  *
- *  @details Pointer to this strucutre is passed in the call to @ref netapi_schedOpen API
+ *  @details Pointer to this structure is passed in the call to @ref netapi_schedOpen API
  */
 typedef struct NETAPI_SCHED_CONFIG_Tag
 {
 
-    int valid_flags; /**< This define valid flags options of scheduler context being configured */
+/**
+ * Valid flag options of scheduler context being configured.
+ * <br>
+ * The following are flags used to configure the scheduler:
+ *      @ref NETAPI_SCHED_DURATION , @ref NETAPI_SCHED_POWER, @ref NETAPI_SCHED_FINE, @ref NETAPI_SCHED_FINE
+ */
+    int valid_flags;
 
 /**
  * @def NETAPI_SCHED_DURATION
- *      This define duration option  of scheduler context being configured.
+ * @ingroup sched_constants
+ *      This defines the duration option  of scheduler context being configured TBD
  */
 #define NETAPI_SCHED_DURATION 0x1
 
 /**
  * @def NETAPI_SCHED_POWER
- *      This define the Power option  of scheduler context being configured. TBD
+ * @ingroup sched_constants
+ *      This defines the Power option  of scheduler context being configured. TBD
  */
 #define NETAPI_SCHED_POWER 0x2
 
 /**
  * @def NETAPI_SCHED_FINE
- *      This define the fine tune option of scheduler context being configured. TBD
+ * @ingroup sched_constants
+ *      This defines the fine tune option of scheduler context being configured. TBD
  */
 #define NETAPI_SCHED_FINE  0x4
 
 /**
  * @def NETAPI_SCHED_CBV
- *      This define the call back option of scheduler context being configured. TBD.
+ * @ingroup sched_constants
+ *      This defines the call back option of scheduler context being configured. TBD.
  */
 #define NETAPI_SCHED_CBV  0x8
 
 /**
  * @def NETAPI_SCHED_FOREVER
- *      This define is used to configure scheduler to run forever.
+ * @ingroup sched_constants
+ *      This defines is used to configure scheduler to run forever.
  */
 #define NETAPI_SCHED_FOREVER 0L
 
@@ -122,17 +129,24 @@ typedef struct NETAPI_SCHED_CONFIG_Tag
 
     uint32_t interval;                      /**< How many poll loop intervals after which to call the house keeping callback */ 
 
-
-    int power_control;                          /**< 0 = always on, >0 = duty cycle  TBD */
+/**
+ * Power control option configuration for scheduler
+ * <br>
+ * The following are flags used to configure the power control option:
+ *      @ref NETAPI_SCHED_POWER_ALWAYS_OFF , @ref NETAPI_SCHED_POWER_ALWAYS_OFF
+ */
+    int power_control;
 
 /**
  * @def NETAPI_SCHED_POWER_ALWAYS_OFF
+ * @ingroup sched_constants
  *      This define is used to configure scheduler power_control option to be always off TBD
  */
 #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
  */
 #define NETAPI_SCHED_POWER_ALWAYS_ON 100
@@ -143,38 +157,47 @@ typedef struct NETAPI_SCHED_CONFIG_Tag
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup sched_structures
  *  @brief NETAPI scheduler context handle.
  *
  *  @details  This structure is returned from call to @ref netapi_schedOpen API
  */
 typedef struct NETAPI_SCHED_HANDLE_Tag
 {
+/**
+ * State of the scheduler
+ * <br>
+ * The following are valid states of the scheduler, 
+ *      @ref NETAPI_SCHED_STATE_CLOSE , @ref NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS, @ref NETAPI_SCHED_STATE_OPEN
+ */
     volatile int state;                /**< 0= shutdown, 1= shutting down, 2=active */
 
 /**
  * @def NETAPI_SCHED_STATE_CLOSE
+ * @ingroup sched_constants
  *      This define indicates the state of the scheduler to be CLOSE (idle) state TBD
  */
 #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
  */
 #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
  */
 #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 */
-    volatile uint64_t shutdown_time;   /**< Time till scheduler context will be shutdown/closed */
+    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 */
+    volatile uint64_t shutdown_time;    /**< Time till scheduler context will be shutdown/closed */
 
 } NETAPI_SCHED_HANDLE_T;
 
@@ -183,36 +206,45 @@ typedef struct NETAPI_SCHED_HANDLE_Tag
 
 /// @cond FUTURE
 /* return codes for wait_for_events() TBD, 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
+#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 */
 /// @endcond
 
 
 
 /**
- *  @ingroup netapi_structures
+ *  @ingroup sched_structures
  *  @brief NETAPI scheduler shutdown structure
  *  @details  This structure is passed an an argument for @ref netapi_schedShutdown
  */
 typedef struct NETAPI_SCHED_SHUTDOWN_Tag
 {
+/**
+ * Scheduler shutdown options
+ * <br>
+ * The following options of how to shutdown the scheduler
+ *      @ref NETAPI_SCHED_SHUTDOWN_NOW , @ref NETAPI_SCHED_SHUTDOWN_TO, @ref NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
+ */
     int shutdown_type;                      /**< shutdown type */
 
 /**
  * @def NETAPI_SCHED_SHUTDOWN_NOW
+ * @ingroup sched_constants
  *      This define is used to shudown the scheduling context immediately 
  */
 #define NETAPI_SCHED_SHUTDOWN_NOW 0
 
 /**
  * @def NETAPI_SCHED_SHUTDOWN_TO
+ * @ingroup sched_constants
  *      This define is used to shudown the scheduling context TBD
  */
 #define NETAPI_SCHED_SHUTDOWN_TO  1
 
 /**
  * @def NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
+ * @ingroup sched_constants
  *      This define is used to shudown the scheduling context during next idle period
  */
 #define NETAPI_SCHED_SHUTDOWN_NEXT_IDLE  2
@@ -221,7 +253,7 @@ typedef struct NETAPI_SCHED_SHUTDOWN_Tag
 } NETAPI_SCHED_SHUTDOWN_T;
 
 /**
- *  @ingroup netapi_sched_functions
+ *  @ingroup sched_functions
  *  @brief netapi_schedOpen: API to open a scheduling context
  *
  *  @details API to open a scheduling context
@@ -237,7 +269,7 @@ NETAPI_SCHED_HANDLE_T * netapi_schedOpen(NETAPI_T n,
 
 
 /**
- *  @ingroup netapi_sched_functions
+ *  @ingroup sched_functions
  *  @brief netapi_schedControl: API to re-configure a scheduling context, FUTURE, not implemented
  *
  *  @details API to re-configure a scheduling context
@@ -253,7 +285,7 @@ int netapi_schedControl(NETAPI_SCHED_HANDLE_T *s,
 
 
 /**
- *  @ingroup netapi_sched_functions
+ *  @ingroup sched_functions
  *  @brief netapi_schedWaitForEvents: API for main entry point to scheduler.
  *
  *  @details API for main entry point to scheduler. User application gives up control to scheduler.
@@ -266,7 +298,7 @@ int netapi_schedWaitForEvents(NETAPI_SCHED_HANDLE_T *s,
                               int * p_err);
 
 /**
- *  @ingroup netapi_sched_functions
+ *  @ingroup sched_functions
  *  @brief netapi_schedShutdown: API to shutdown scheduling context
  *
  *  @details API to shutdown scheduling context
@@ -281,7 +313,7 @@ int netapi_schedShutdown(NETAPI_SCHED_HANDLE_T * s,
                          int *p_err);
 
 /**
- *  @ingroup netapi_sched_functions
+ *  @ingroup sched_functions
  *  @brief netapi_schedShutdown: API to get the NETAPI handle from scheduling context 
  *
  *  @details API to get the NETAPI handle from scheduling context 
@@ -289,13 +321,15 @@ int netapi_schedShutdown(NETAPI_SCHED_HANDLE_T * s,
  *  @retval     Handle to NETAPI instance
  */
 static NETAPI_T netapi_schedGetNetapiHandle(NETAPI_SCHED_HANDLE_T *s)
-  { return (NETAPI_T)s->back;}
+{
+    return (NETAPI_T)s->back;
+}
 
 
 
 
 /**
- *  @ingroup netapi_sched_functions
+ *  @ingroup sched_functions
  *  @brief netapi_sched_get_stats: API to tget NETAP scheduling context statistics
  *
  *  @details   API to tget NETAP scheduling context statistics