Removed doxygen directory and contents
[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.  Each transport application thread should have its own scheduler context.
55  */
56 struct  NETAPI_SCHED_HANDLE_Tag;
59 /**
60  *  @ingroup netapi_cb_functions
61  *  @brief NETAPI_SCHED_CB   Callback function for scheduling context house 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
62  * 
63  *  @details The application provides a callback function that NETAPI scheduling context  will call on  a periodic/ low priority basis.
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  */
92 #define NETAPI_SCHED_DURATION 0x1
94 /**
95  * @def NETAPI_SCHED_POWER
96  * @ingroup sched_constants
97  *      This defines the Power option  of scheduler context being configured.  FUTURE
98  */
99 #define NETAPI_SCHED_POWER 0x2
101 /**
102  * @def NETAPI_SCHED_FINE
103  * @ingroup sched_constants
104  *      This defines the fine tune option of scheduler context being configured. FUTURE
105  */
106 #define NETAPI_SCHED_FINE  0x4
108 /**
109  * @def NETAPI_SCHED_CBV
110  * @ingroup sched_constants
111  *      This defines that the housekeeping   call back option of scheduler context has been configured.
112  */
113 #define NETAPI_SCHED_CBV  0x8
115 /**
116  * @def NETAPI_SCHED_FOREVER
117  * @ingroup sched_constants
118  *      This defines is used to configure scheduler to run forever.
119  */
120 #define NETAPI_SCHED_FOREVER 0L
122     uint64_t duration;                      /**< Duration scheduler is configured to run, 0 == forever, 
123                                               * non-zero value is ticks for scheduler to run
124                                               */
127     NETAPI_SCHED_CB house_cb;               /**< House keeping callback */
129     uint32_t interval;                      /**< How many poll loop intervals after which to call the house keeping callback */ 
131 /**
132  * Power control option configuration for scheduler
133  * <br>
134  * The following are flags used to configure the power control option:
135  *      @ref NETAPI_SCHED_POWER_ALWAYS_OFF , @ref NETAPI_SCHED_POWER_ALWAYS_OFF
136  */
137     int power_control;
139 /**
140  * @def NETAPI_SCHED_POWER_ALWAYS_OFF
141  * @ingroup sched_constants
142  *      This define is used to configure scheduler power_control option to be always off  FUTURE
143  */
144 #define NETAPI_SCHED_POWER_ALWAYS_OFF 0
146 /**
147  * @def NETAPI_SCHED_POWER_ALWAYS_ON
148  * @ingroup sched_constants
149  *      This define is used to configure scheduler power_control option to be always on FUTURE
150  */
151 #define NETAPI_SCHED_POWER_ALWAYS_ON 100
153     int idle_time;                          /**< idle time  */
154 } NETAPI_SCHED_CONFIG_T;
158 /**
159  *  @ingroup sched_structures
160  *  @brief NETAPI scheduler context handle.
161  *
162  *  @details  This structure is returned from call to @ref netapi_schedOpen API
163  */
164 typedef struct NETAPI_SCHED_HANDLE_Tag
166 /**
167  * State of the scheduler
168  * <br>
169  * The following are valid states of the scheduler, 
170  *      @ref NETAPI_SCHED_STATE_CLOSE , @ref NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS, @ref NETAPI_SCHED_STATE_OPEN
171  */
172     volatile int state;                /**< 0= shutdown, 1= shutting down, 2=active */
174 /**
175  * @def NETAPI_SCHED_STATE_CLOSE
176  * @ingroup sched_constants
177  *      This define indicates the state of the scheduler to be CLOSE (idle) state
178  */
179 #define NETAPI_SCHED_STATE_CLOSE 0
181 /**
182  * @def NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS
183  * @ingroup sched_constants
184  *      This define indicates the state of the scheduler is being shutdown state
185  */
186 #define NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS 1
188 /**
189  * @def NETAPI_SCHED_STATE_OPEN
190  * @ingroup sched_constants
191  *      This define indicates the state of the scheduler is OPEN (running)
192  */
193 #define NETAPI_SCHED_STATE_OPEN 2
195     void * back;                        /**< Pointer back to NETAPI  handle */
196     NETAPI_SCHED_CONFIG_T config;       /**< NETAPI scheduler configuration */
197     uint64_t start;                     /**< Start time of NETAPI scheduler context */ 
198     volatile int shutdown_reason;       /**< FUTURE-not implemented  */
199     volatile uint64_t shutdown_time;    /**< Time till scheduler context will be shutdown/closed */
201 } NETAPI_SCHED_HANDLE_T;
206 /// @cond FUTURE
207 /* return codes for wait_for_events()  currently not used*/
208 #define NETAPI_SCHED_RETURN_ERR         0       /**<unknown, err */
209 #define NETAPI_SCHED_RETURN_TO          1       /**<returned after timeout */
210 #define NETAPI_SCHED_RETURN_SHUTDOWN    2       /**<returned after shutdown */
211 /// @endcond
215 /**
216  *  @ingroup sched_structures
217  *  @brief NETAPI scheduler shutdown structure
218  *  @details  This structure is passed an an argument for @ref netapi_schedShutdown
219  */
220 typedef struct NETAPI_SCHED_SHUTDOWN_Tag
222 /**
223  * Scheduler shutdown options
224  * <br>
225  * The following options of how to shutdown the scheduler
226  *      @ref NETAPI_SCHED_SHUTDOWN_NOW , @ref NETAPI_SCHED_SHUTDOWN_TO, @ref NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
227  */
228     int shutdown_type;                      /**< shutdown type */
230 /**
231  * @def NETAPI_SCHED_SHUTDOWN_NOW
232  * @ingroup sched_constants
233  *      This define is used to shudown the scheduling context immediately 
234  */
235 #define NETAPI_SCHED_SHUTDOWN_NOW 0
237 /**
238  * @def NETAPI_SCHED_SHUTDOWN_TO
239  * @ingroup sched_constants
240  *      This define is used to shudown the scheduling context after a short while. FUTURE 
241  */
242 #define NETAPI_SCHED_SHUTDOWN_TO  1
244 /**
245  * @def NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
246  * @ingroup sched_constants
247  *      This define is used to shudown the scheduling context during next idle period
248  */
249 #define NETAPI_SCHED_SHUTDOWN_NEXT_IDLE  2
251     int timeout;                            /**< Ticks from now to close the scheduling context */
252 } NETAPI_SCHED_SHUTDOWN_T;
254 /**
255  *  @ingroup sched_functions
256  *  @brief netapi_schedOpen: API to open a scheduling context
257  *
258  *  @details API to open a scheduling context
259  *  @param[in]  n   the NETAPI handle, @ref NETAPI_T
260  *  @param[in] p_config :pointer to @ref NETAPI_SCHED_CONFIG_T
261   *  @param[out] p_err    Pointer to error code.
262  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
263  *  @pre        @ref netapi_init 
264  */
265 NETAPI_SCHED_HANDLE_T * netapi_schedOpen(NETAPI_T n,
266                                          NETAPI_SCHED_CONFIG_T * p_config,
267                                          int *p_err);
270 /**
271  *  @ingroup sched_functions
272  *  @brief netapi_schedControl: API to re-configure a scheduling context, FUTURE, not implemented
273  *
274  *  @details API to re-configure a scheduling context
275  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
276  *  @param[in] p_config     Pointer to @ref NETAPI_SCHED_CONFIG_T
277  *  @param[out] p_err    Pointer to error code.
278  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
279  *  @pre        @ref netapi_schedOpen 
280  */
281 int netapi_schedControl(NETAPI_SCHED_HANDLE_T *s,
282                         NETAPI_SCHED_CONFIG_T *p_config,
283                         int *p_err);
286 /**
287  *  @ingroup sched_functions
288  *  @brief netapi_schedWaitForEvents: API for main entry point to scheduler.
289  *
290  *  @details API for main entry point to scheduler. User application gives up control to scheduler.
291   *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
292  *  @param[out] p_err: error code, zero on sucess, non-zero on failure
293  *  @retval     always 1
294  *  @pre        @ref netapi_schedOpen 
295  */
296 int netapi_schedWaitForEvents(NETAPI_SCHED_HANDLE_T *s,
297                               int * p_err);
299 /**
300  *  @ingroup sched_functions
301  *  @brief netapi_schedShutdown: API to shutdown scheduling context
302  *
303  *  @details API to shutdown scheduling context
304  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
305  *  @param[in]  p_close  @ref NETAPI_SCHED_SHUTDOWN_T
306  *  @param[out] p_err    Pointer to error code.
307  *  @retval     NO USED, ALWAYS 1
308  *  @pre        @ref netapi_schedOpen 
309  */
310 int netapi_schedShutdown(NETAPI_SCHED_HANDLE_T * s, 
311                          NETAPI_SCHED_SHUTDOWN_T * p_close,
312                          int *p_err);
314 /**
315  *  @ingroup sched_functions
316  *  @brief netapi_schedShutdown: API to get the NETAPI handle from scheduling context 
317  *
318  *  @details API to get the NETAPI handle from scheduling context 
319  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
320  *  @retval     Handle to NETAPI instance
321  */
322 static NETAPI_T netapi_schedGetNetapiHandle(NETAPI_SCHED_HANDLE_T *s)
324     return (NETAPI_T)s->back;
330 /**
331  *  @ingroup sched_functions
332  *  @brief netapi_sched_get_stats: API to get NETAP scheduling context statistics
333  *
334  *  @details   API to tget NETAP scheduling context statistics
335  *  @param[in]  p_pkts  total number of packets processed by scheduler poll loop
336  *  @param[in]  p_cycles total number cycles taken by scheduler poll loop
337  *  @param[in]  p_ccycles  total number of cache control cycles taken by scheduler poll loop
338  *  @retval     none
339  */
340 void netapi_sched_get_stats(unsigned long long * p_pkts, 
341                             unsigned long long * p_cycles,
342                             unsigned long long * p_ccycles);
343 #endif