Additional doxygen updates
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi_sched.h
1 /******************************************************************************
2  * FILE PURPOSE:  Netapi  scheduler module
3  ******************************************************************************
4  * FILE NAME:   netapi_sched.h
5  *
6  * DESCRIPTION: Netapi sample event scheduler  header file for  user space transport library
7  *
8  * REVISION HISTORY:
9  *
10  *  Copyright (c) Texas Instruments Incorporated 2010-2011
11  *
12  *  Redistribution and use in source and binary forms, with or without
13  *  modification, are permitted provided that the following conditions
14  *  are met:
15  *
16  *    Redistributions of source code must retain the above copyright
17  *    notice, this list of conditions and the following disclaimer.
18  *
19  *    Redistributions in binary form must reproduce the above copyright
20  *    notice, this list of conditions and the following disclaimer in the
21  *    documentation and/or other materials provided with the
22  *    distribution.
23  *
24  *    Neither the name of Texas Instruments Incorporated nor the names of
25  *    its contributors may be used to endorse or promote products derived
26  *    from this software without specific prior written permission.
27  *
28  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
31  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
32  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
33  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
34  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
35  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
36  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
37  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
38  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
39  *
40  */
41 /* ============================================================= */
43 /**
44  *  @file netapi_sched.h
45  *  @brief netapi scheduler header file for user space transport library
46  */
49 #ifndef __NETAPI_SCHED__
50 #define __NETAPI_SCHED__
51 #include "netapi.h"
53 /**
54  * @brief This define the handle to the NETAPI scheduling context TBD
55  */
56 struct  NETAPI_SCHED_HANDLE_Tag;
59 /**
60  *  @ingroup netapi_cb_functions
61  *  @brief NETAPI_SCHED_CB   Callback function for scheduling context hous keeping. TBD
62  * 
63  *  @details The application provides a callback function that NETAPI scheduling context to retrieve TBD
64  *  @param[in]  h   The handle to the NETAPI scheduling context
65  *  @retval     none 
66  *  @pre       @ref netapi_init
67  */
68 typedef void (*NETAPI_SCHED_CB)(struct NETAPI_SCHED_HANDLE_Tag *h);
71 /**
72  *  @ingroup sched_structures
73  *  @brief NETAPI scheduler configuration structure.
74  *
75  *  @details Pointer to this structure is passed in the call to @ref netapi_schedOpen API
76  */
77 typedef struct NETAPI_SCHED_CONFIG_Tag
78 {
80 /**
81  * Valid flag options of scheduler context being configured.
82  * <br>
83  * The following are flags used to configure the scheduler:
84  *      @ref NETAPI_SCHED_DURATION , @ref NETAPI_SCHED_POWER, @ref NETAPI_SCHED_FINE, @ref NETAPI_SCHED_FINE
85  */
86     int valid_flags;
88 /**
89  * @def NETAPI_SCHED_DURATION
90  * @ingroup sched_constants
91  *      This defines the duration option  of scheduler context being configured TBD
92  */
93 #define NETAPI_SCHED_DURATION 0x1
95 /**
96  * @def NETAPI_SCHED_POWER
97  * @ingroup sched_constants
98  *      This defines the Power option  of scheduler context being configured. TBD
99  */
100 #define NETAPI_SCHED_POWER 0x2
102 /**
103  * @def NETAPI_SCHED_FINE
104  * @ingroup sched_constants
105  *      This defines the fine tune option of scheduler context being configured. TBD
106  */
107 #define NETAPI_SCHED_FINE  0x4
109 /**
110  * @def NETAPI_SCHED_CBV
111  * @ingroup sched_constants
112  *      This defines the call back option of scheduler context being configured. TBD.
113  */
114 #define NETAPI_SCHED_CBV  0x8
116 /**
117  * @def NETAPI_SCHED_FOREVER
118  * @ingroup sched_constants
119  *      This defines is used to configure scheduler to run forever.
120  */
121 #define NETAPI_SCHED_FOREVER 0L
123     uint64_t duration;                      /**< Duration scheduler is configured to run, 0 == forever, 
124                                               * non-zero value is ticks for scheduler to run
125                                               */
128     NETAPI_SCHED_CB house_cb;               /**< House keeping callback */
130     uint32_t interval;                      /**< How many poll loop intervals after which to call the house keeping callback */ 
132 /**
133  * Power control option configuration for scheduler
134  * <br>
135  * The following are flags used to configure the power control option:
136  *      @ref NETAPI_SCHED_POWER_ALWAYS_OFF , @ref NETAPI_SCHED_POWER_ALWAYS_OFF
137  */
138     int power_control;
140 /**
141  * @def NETAPI_SCHED_POWER_ALWAYS_OFF
142  * @ingroup sched_constants
143  *      This define is used to configure scheduler power_control option to be always off TBD
144  */
145 #define NETAPI_SCHED_POWER_ALWAYS_OFF 0
147 /**
148  * @def NETAPI_SCHED_POWER_ALWAYS_ON
149  * @ingroup sched_constants
150  *      This define is used to configure scheduler power_control option to be always on
151  */
152 #define NETAPI_SCHED_POWER_ALWAYS_ON 100
154     int idle_time;                          /**< idle time TBD */
155 } NETAPI_SCHED_CONFIG_T;
159 /**
160  *  @ingroup sched_structures
161  *  @brief NETAPI scheduler context handle.
162  *
163  *  @details  This structure is returned from call to @ref netapi_schedOpen API
164  */
165 typedef struct NETAPI_SCHED_HANDLE_Tag
167 /**
168  * State of the scheduler
169  * <br>
170  * The following are valid states of the scheduler, 
171  *      @ref NETAPI_SCHED_STATE_CLOSE , @ref NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS, @ref NETAPI_SCHED_STATE_OPEN
172  */
173     volatile int state;                /**< 0= shutdown, 1= shutting down, 2=active */
175 /**
176  * @def NETAPI_SCHED_STATE_CLOSE
177  * @ingroup sched_constants
178  *      This define indicates the state of the scheduler to be CLOSE (idle) state TBD
179  */
180 #define NETAPI_SCHED_STATE_CLOSE 0
182 /**
183  * @def NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS
184  * @ingroup sched_constants
185  *      This define indicates the state of the scheduler is being shutdown state TBD
186  */
187 #define NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS 1
189 /**
190  * @def NETAPI_SCHED_STATE_OPEN
191  * @ingroup sched_constants
192  *      This define indicates the state of the scheduler is OPEN (running) TBD
193  */
194 #define NETAPI_SCHED_STATE_OPEN 2
196     void * back;                        /**< Pointer back to NETAPI  handle */
197     NETAPI_SCHED_CONFIG_T config;       /**< NETAPI scheduler configuration */
198     uint64_t start;                     /**< Start time of NETAPI scheduler context TBD*/ 
199     volatile int shutdown_reason;       /**< FUTURE-not implemented TBD */
200     volatile uint64_t shutdown_time;    /**< Time till scheduler context will be shutdown/closed */
202 } NETAPI_SCHED_HANDLE_T;
207 /// @cond FUTURE
208 /* return codes for wait_for_events() TBD, currently not used*/
209 #define NETAPI_SCHED_RETURN_ERR         0       /**<unknown, err */
210 #define NETAPI_SCHED_RETURN_TO          1       /**<returned after timeout */
211 #define NETAPI_SCHED_RETURN_SHUTDOWN    2       /**<returned after shutdown */
212 /// @endcond
216 /**
217  *  @ingroup sched_structures
218  *  @brief NETAPI scheduler shutdown structure
219  *  @details  This structure is passed an an argument for @ref netapi_schedShutdown
220  */
221 typedef struct NETAPI_SCHED_SHUTDOWN_Tag
223 /**
224  * Scheduler shutdown options
225  * <br>
226  * The following options of how to shutdown the scheduler
227  *      @ref NETAPI_SCHED_SHUTDOWN_NOW , @ref NETAPI_SCHED_SHUTDOWN_TO, @ref NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
228  */
229     int shutdown_type;                      /**< shutdown type */
231 /**
232  * @def NETAPI_SCHED_SHUTDOWN_NOW
233  * @ingroup sched_constants
234  *      This define is used to shudown the scheduling context immediately 
235  */
236 #define NETAPI_SCHED_SHUTDOWN_NOW 0
238 /**
239  * @def NETAPI_SCHED_SHUTDOWN_TO
240  * @ingroup sched_constants
241  *      This define is used to shudown the scheduling context TBD
242  */
243 #define NETAPI_SCHED_SHUTDOWN_TO  1
245 /**
246  * @def NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
247  * @ingroup sched_constants
248  *      This define is used to shudown the scheduling context during next idle period
249  */
250 #define NETAPI_SCHED_SHUTDOWN_NEXT_IDLE  2
252     int timeout;                            /**< Ticks from now to close the scheduling context */
253 } NETAPI_SCHED_SHUTDOWN_T;
255 /**
256  *  @ingroup sched_functions
257  *  @brief netapi_schedOpen: API to open a scheduling context
258  *
259  *  @details API to open a scheduling context
260  *  @param[in]  n   the NETAPI handle, @ref NETAPI_T
261  *  @param[in] p_config :pointer to @ref NETAPI_SCHED_CONFIG_T
262   *  @param[out] p_err    Pointer to error code.
263  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
264  *  @pre        @ref netapi_init 
265  */
266 NETAPI_SCHED_HANDLE_T * netapi_schedOpen(NETAPI_T n,
267                                          NETAPI_SCHED_CONFIG_T * p_config,
268                                          int *p_err);
271 /**
272  *  @ingroup sched_functions
273  *  @brief netapi_schedControl: API to re-configure a scheduling context, FUTURE, not implemented
274  *
275  *  @details API to re-configure a scheduling context
276  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
277  *  @param[in] p_config     Pointer to @ref NETAPI_SCHED_CONFIG_T
278  *  @param[out] p_err    Pointer to error code.
279  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
280  *  @pre        @ref netapi_schedOpen 
281  */
282 int netapi_schedControl(NETAPI_SCHED_HANDLE_T *s,
283                         NETAPI_SCHED_CONFIG_T *p_config,
284                         int *p_err);
287 /**
288  *  @ingroup sched_functions
289  *  @brief netapi_schedWaitForEvents: API for main entry point to scheduler.
290  *
291  *  @details API for main entry point to scheduler. User application gives up control to scheduler.
292   *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
293  *  @param[out] p_err: error code, zero on sucess, non-zero on failure
294  *  @retval     TBD
295  *  @pre        @ref netapi_schedOpen 
296  */
297 int netapi_schedWaitForEvents(NETAPI_SCHED_HANDLE_T *s,
298                               int * p_err);
300 /**
301  *  @ingroup sched_functions
302  *  @brief netapi_schedShutdown: API to shutdown scheduling context
303  *
304  *  @details API to shutdown scheduling context
305  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
306  *  @param[in]  p_close  @ref NETAPI_SCHED_SHUTDOWN_T
307  *  @param[out] p_err    Pointer to error code.
308  *  @retval     TBD
309  *  @pre        @ref netapi_schedOpen 
310  */
311 int netapi_schedShutdown(NETAPI_SCHED_HANDLE_T * s, 
312                          NETAPI_SCHED_SHUTDOWN_T * p_close,
313                          int *p_err);
315 /**
316  *  @ingroup sched_functions
317  *  @brief netapi_schedShutdown: API to get the NETAPI handle from scheduling context 
318  *
319  *  @details API to get the NETAPI handle from scheduling context 
320  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
321  *  @retval     Handle to NETAPI instance
322  */
323 static NETAPI_T netapi_schedGetNetapiHandle(NETAPI_SCHED_HANDLE_T *s)
325     return (NETAPI_T)s->back;
331 /**
332  *  @ingroup sched_functions
333  *  @brief netapi_sched_get_stats: API to tget NETAP scheduling context statistics
334  *
335  *  @details   API to tget NETAP scheduling context statistics
336  *  @param[in]  p_pkts TBD
337  *  @param[in]  p_cycles TBD
338  *  @param[in]  p_ccycles TBD
339  *  @retval     none
340  */
341 void netapi_sched_get_stats(unsigned long long * p_pkts, 
342                             unsigned long long * p_cycles,
343                             unsigned long long * p_ccycles);
344 #endif