Merge remote branch 'origin/master' into netapi-keystone2
[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 TBD */
155     Bool  yield;                /**< option of thread/core to yield in scheduling loop in no pkts from to process */
156     Bool pollCtrlQ;             /**< option to poll the control queue in scheduling loop */
157     Bool pollGarbageQ;          /**< option to poll the garbage  queue in scheduling loop */
158 } NETAPI_SCHED_CONFIG_T;
162 /**
163  *  @ingroup sched_structures
164  *  @brief NETAPI scheduler context handle.
165  *
166  *  @details  This structure is returned from call to @ref netapi_schedOpen API
167  */
168 typedef struct NETAPI_SCHED_HANDLE_Tag
170 /**
171  * State of the scheduler
172  * <br>
173  * The following are valid states of the scheduler, 
174  *      @ref NETAPI_SCHED_STATE_CLOSE , @ref NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS, @ref NETAPI_SCHED_STATE_OPEN
175  */
176     volatile int state;                /**< 0= shutdown, 1= shutting down, 2=active */
178 /**
179  * @def NETAPI_SCHED_STATE_CLOSE
180  * @ingroup sched_constants
181  *      This define indicates the state of the scheduler to be CLOSE (idle) state
182  */
183 #define NETAPI_SCHED_STATE_CLOSE 0
185 /**
186  * @def NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS
187  * @ingroup sched_constants
188  *      This define indicates the state of the scheduler is being shutdown state
189  */
190 #define NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS 1
192 /**
193  * @def NETAPI_SCHED_STATE_OPEN
194  * @ingroup sched_constants
195  *      This define indicates the state of the scheduler is OPEN (running)
196  */
197 #define NETAPI_SCHED_STATE_OPEN 2
199     void * back;                        /**< Pointer back to NETAPI  handle */
200     NETAPI_SCHED_CONFIG_T config;       /**< NETAPI scheduler configuration */
201     uint64_t start;                     /**< Start time of NETAPI scheduler context */ 
202     volatile int shutdown_reason;       /**< FUTURE-not implemented  */
203     volatile uint64_t shutdown_time;    /**< Time till scheduler context will be shutdown/closed */
204 unsigned long long num_pkts;
205 unsigned long long busy_cycles;
206 unsigned long long cache_cycles;
208 } NETAPI_SCHED_HANDLE_T;
213 /// @cond FUTURE
214 /* return codes for wait_for_events()  currently not used*/
215 #define NETAPI_SCHED_RETURN_ERR         0       /**<unknown, err */
216 #define NETAPI_SCHED_RETURN_TO          1       /**<returned after timeout */
217 #define NETAPI_SCHED_RETURN_SHUTDOWN    2       /**<returned after shutdown */
218 /// @endcond
222 /**
223  *  @ingroup sched_structures
224  *  @brief NETAPI scheduler shutdown structure
225  *  @details  This structure is passed an an argument for @ref netapi_schedShutdown
226  */
227 typedef struct NETAPI_SCHED_SHUTDOWN_Tag
229 /**
230  * Scheduler shutdown options
231  * <br>
232  * The following options of how to shutdown the scheduler
233  *      @ref NETAPI_SCHED_SHUTDOWN_NOW , @ref NETAPI_SCHED_SHUTDOWN_TO, @ref NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
234  */
235     int shutdown_type;                      /**< shutdown type */
237 /**
238  * @def NETAPI_SCHED_SHUTDOWN_NOW
239  * @ingroup sched_constants
240  *      This define is used to shudown the scheduling context immediately 
241  */
242 #define NETAPI_SCHED_SHUTDOWN_NOW 0
244 /**
245  * @def NETAPI_SCHED_SHUTDOWN_TO
246  * @ingroup sched_constants
247  *      This define is used to shudown the scheduling context after a short while. FUTURE 
248  */
249 #define NETAPI_SCHED_SHUTDOWN_TO  1
251 /**
252  * @def NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
253  * @ingroup sched_constants
254  *      This define is used to shudown the scheduling context during next idle period
255  */
256 #define NETAPI_SCHED_SHUTDOWN_NEXT_IDLE  2
258     int timeout;                            /**< Ticks from now to close the scheduling context */
259 } NETAPI_SCHED_SHUTDOWN_T;
261 /**
262  *  @ingroup sched_functions
263  *  @brief netapi_schedOpen: API to open a scheduling context
264  *
265  *  @details API to open a scheduling context
266  *  @param[in]  n   the NETAPI handle, @ref NETAPI_T
267  *  @param[in] p_config :pointer to @ref NETAPI_SCHED_CONFIG_T
268   *  @param[out] p_err    Pointer to error code.
269  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
270  *  @pre        @ref netapi_init 
271  */
272 NETAPI_SCHED_HANDLE_T * netapi_schedOpen(NETAPI_T n,
273                                          NETAPI_SCHED_CONFIG_T * p_config,
274                                          int *p_err);
277 /**
278  *  @ingroup sched_functions
279  *  @brief netapi_schedControl: API to re-configure a scheduling context, FUTURE, not implemented
280  *
281  *  @details API to re-configure a scheduling context
282  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
283  *  @param[in] p_config     Pointer to @ref NETAPI_SCHED_CONFIG_T
284  *  @param[out] p_err    Pointer to error code.
285  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
286  *  @pre        @ref netapi_schedOpen 
287  */
288 int netapi_schedControl(NETAPI_SCHED_HANDLE_T *s,
289                         NETAPI_SCHED_CONFIG_T *p_config,
290                         int *p_err);
293 /**
294  *  @ingroup sched_functions
295  *  @brief netapi_schedWaitForEvents: API for main entry point to scheduler.
296  *
297  *  @details API for main entry point to scheduler. User application gives up control to scheduler.
298   *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
299  *  @param[out] p_err: error code, zero on sucess, non-zero on failure
300  *  @retval     always 1
301  *  @pre        @ref netapi_schedOpen 
302  */
303 int netapi_schedWaitForEvents(NETAPI_SCHED_HANDLE_T *s,
304                               int * p_err);
306 /**
307  *  @ingroup sched_functions
308  *  @brief netapi_schedShutdown: API to shutdown scheduling context
309  *
310  *  @details API to shutdown scheduling context
311  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
312  *  @param[in]  p_close  @ref NETAPI_SCHED_SHUTDOWN_T
313  *  @param[out] p_err    Pointer to error code.
314  *  @retval     NO USED, ALWAYS 1
315  *  @pre        @ref netapi_schedOpen 
316  */
317 int netapi_schedShutdown(NETAPI_SCHED_HANDLE_T * s, 
318                          NETAPI_SCHED_SHUTDOWN_T * p_close,
319                          int *p_err);
321 /**
322  *  @ingroup sched_functions
323  *  @brief netapi_schedShutdown: API to get the NETAPI handle from scheduling context 
324  *
325  *  @details API to get the NETAPI handle from scheduling context 
326  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
327  *  @retval     Handle to NETAPI instance
328  */
329 static NETAPI_T netapi_schedGetNetapiHandle(NETAPI_SCHED_HANDLE_T *s)
331     return (NETAPI_T)s->back;
337 /**
338  *  @ingroup sched_functions
339  *  @brief netapi_sched_get_stats: API to get NETAP scheduling context statistics
340  *
341  *  @details   API to tget NETAP scheduling context statistics
342  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
343  *  @param[in]  p_pkts  total number of packets processed by scheduler poll loop
344  *  @param[in]  p_cycles total number cycles taken by scheduler poll loop
345  *  @param[in]  p_ccycles  total number of cache control cycles taken by scheduler poll loop
346  *  @retval     none
347  */
348 void netapi_sched_get_stats(NETAPI_SCHED_HANDLE_T *s,
349                                                         unsigned long long * p_pkts, 
350                                                         unsigned long long * p_cycles,
351                                                         unsigned long long * p_ccycles);
352 #endif