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);
75 /**
76  *  @ingroup netapi_structures
77  *  @brief NETAPI scheduler configuration structure.
78  *
79  *  @details Pointer to this strucutre is passed in the call to @ref netapi_schedOpen API
80  */
81 typedef struct NETAPI_SCHED_CONFIG_Tag
82 {
84     int valid_flags; /**< This define valid flags options of scheduler context being configured */
86 /**
87  * @def NETAPI_SCHED_DURATION
88  *      This define duration option  of scheduler context being configured.
89  */
90 #define NETAPI_SCHED_DURATION 0x1
92 /**
93  * @def NETAPI_SCHED_POWER
94  *      This define the Power option  of scheduler context being configured. TBD
95  */
96 #define NETAPI_SCHED_POWER 0x2
98 /**
99  * @def NETAPI_SCHED_FINE
100  *      This define the fine tune option of scheduler context being configured. TBD
101  */
102 #define NETAPI_SCHED_FINE  0x4
104 /**
105  * @def NETAPI_SCHED_CBV
106  *      This define the call back option of scheduler context being configured. TBD.
107  */
108 #define NETAPI_SCHED_CBV  0x8
110 /**
111  * @def NETAPI_SCHED_FOREVER
112  *      This define is used to configure scheduler to run forever.
113  */
114 #define NETAPI_SCHED_FOREVER 0L
116     uint64_t duration;                      /**< Duration scheduler is configured to run, 0 == forever, 
117                                               * non-zero value is ticks for scheduler to run
118                                               */
121     NETAPI_SCHED_CB house_cb;               /**< House keeping callback */
123     uint32_t interval;                      /**< How many poll loop intervals after which to call the house keeping callback */ 
126     int power_control;                          /**< 0 = always on, >0 = duty cycle  TBD */
128 /**
129  * @def NETAPI_SCHED_POWER_ALWAYS_OFF
130  *      This define is used to configure scheduler power_control option to be always off TBD
131  */
132 #define NETAPI_SCHED_POWER_ALWAYS_OFF 0
134 /**
135  * @def NETAPI_SCHED_POWER_ALWAYS_ON
136  *      This define is used to configure scheduler power_control option to be always on
137  */
138 #define NETAPI_SCHED_POWER_ALWAYS_ON 100
140     int idle_time;                          /**< idle time TBD */
141 } NETAPI_SCHED_CONFIG_T;
145 /**
146  *  @ingroup netapi_structures
147  *  @brief NETAPI scheduler context handle.
148  *
149  *  @details  This structure is returned from call to @ref netapi_schedOpen API
150  */
151 typedef struct NETAPI_SCHED_HANDLE_Tag
153     volatile int state;                /**< 0= shutdown, 1= shutting down, 2=active */
155 /**
156  * @def NETAPI_SCHED_STATE_CLOSE
157  *      This define indicates the state of the scheduler to be CLOSE (idle) state TBD
158  */
159 #define NETAPI_SCHED_STATE_CLOSE 0
161 /**
162  * @def NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS
163  *      This define indicates the state of the scheduler is being shutdown state TBD
164  */
165 #define NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS 1
167 /**
168  * @def NETAPI_SCHED_STATE_OPEN
169  *      This define indicates the state of the scheduler is OPEN (running) TBD
170  */
171 #define NETAPI_SCHED_STATE_OPEN 2
173     void * back;                           /**< Pointer back to NETAPI  handle */
174     NETAPI_SCHED_CONFIG_T config;      /**< NETAPI scheduler configuration */
175     uint64_t start;                        /**< Start time of NETAPI scheduler context TBD*/ 
176     volatile int shutdown_reason;  /**< FUTURE-not implemented TBD */
177     volatile uint64_t shutdown_time;   /**< Time till scheduler context will be shutdown/closed */
179 } NETAPI_SCHED_HANDLE_T;
184 /// @cond FUTURE
185 /* return codes for wait_for_events() TBD, currently not used*/
186 #define NETAPI_SCHED_RETURN_ERR 0   //unknown, err
187 #define NETAPI_SCHED_RETURN_TO 1    // returned after timeout
188 #define NETAPI_SCHED_RETURN_SHUTDOWN 2 //returned after shutdown
189 /// @endcond
193 /**
194  *  @ingroup netapi_structures
195  *  @brief NETAPI scheduler shutdown structure
196  *  @details  This structure is passed an an argument for @ref netapi_schedShutdown
197  */
198 typedef struct NETAPI_SCHED_SHUTDOWN_Tag
200     int shutdown_type;                      /**< shutdown type */
202 /**
203  * @def NETAPI_SCHED_SHUTDOWN_NOW
204  *      This define is used to shudown the scheduling context immediately 
205  */
206 #define NETAPI_SCHED_SHUTDOWN_NOW 0
208 /**
209  * @def NETAPI_SCHED_SHUTDOWN_TO
210  *      This define is used to shudown the scheduling context TBD
211  */
212 #define NETAPI_SCHED_SHUTDOWN_TO  1
214 /**
215  * @def NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
216  *      This define is used to shudown the scheduling context during next idle period
217  */
218 #define NETAPI_SCHED_SHUTDOWN_NEXT_IDLE  2
220     int timeout;                            /**< Ticks from now to close the scheduling context */
221 } NETAPI_SCHED_SHUTDOWN_T;
223 /**
224  *  @ingroup netapi_sched_functions
225  *  @brief netapi_schedOpen: API to open a scheduling context
226  *
227  *  @details API to open a scheduling context
228  *  @param[in]  n   the NETAPI handle, @ref NETAPI_T
229  *  @param[in] p_config :pointer to @ref NETAPI_SCHED_CONFIG_T
230   *  @param[out] p_err    Pointer to error code.
231  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
232  *  @pre        @ref netapi_init 
233  */
234 NETAPI_SCHED_HANDLE_T * netapi_schedOpen(NETAPI_T n,
235                                          NETAPI_SCHED_CONFIG_T * p_config,
236                                          int *p_err);
239 /**
240  *  @ingroup netapi_sched_functions
241  *  @brief netapi_schedControl: API to re-configure a scheduling context, FUTURE, not implemented
242  *
243  *  @details API to re-configure a scheduling context
244  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
245  *  @param[in] p_config     Pointer to @ref NETAPI_SCHED_CONFIG_T
246  *  @param[out] p_err    Pointer to error code.
247  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
248  *  @pre        @ref netapi_schedOpen 
249  */
250 int netapi_schedControl(NETAPI_SCHED_HANDLE_T *s,
251                         NETAPI_SCHED_CONFIG_T *p_config,
252                         int *p_err);
255 /**
256  *  @ingroup netapi_sched_functions
257  *  @brief netapi_schedWaitForEvents: API for main entry point to scheduler.
258  *
259  *  @details API for main entry point to scheduler. User application gives up control to scheduler.
260   *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
261  *  @param[out] p_err: error code, zero on sucess, non-zero on failure
262  *  @retval     TBD
263  *  @pre        @ref netapi_schedOpen 
264  */
265 int netapi_schedWaitForEvents(NETAPI_SCHED_HANDLE_T *s,
266                               int * p_err);
268 /**
269  *  @ingroup netapi_sched_functions
270  *  @brief netapi_schedShutdown: API to shutdown scheduling context
271  *
272  *  @details API to shutdown scheduling context
273  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
274  *  @param[in]  p_close  @ref NETAPI_SCHED_SHUTDOWN_T
275  *  @param[out] p_err    Pointer to error code.
276  *  @retval     TBD
277  *  @pre        @ref netapi_schedOpen 
278  */
279 int netapi_schedShutdown(NETAPI_SCHED_HANDLE_T * s, 
280                          NETAPI_SCHED_SHUTDOWN_T * p_close,
281                          int *p_err);
283 /**
284  *  @ingroup netapi_sched_functions
285  *  @brief netapi_schedShutdown: API to get the NETAPI handle from scheduling context 
286  *
287  *  @details API to get the NETAPI handle from scheduling context 
288  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
289  *  @retval     Handle to NETAPI instance
290  */
291 static NETAPI_T netapi_schedGetNetapiHandle(NETAPI_SCHED_HANDLE_T *s)
292   { return (NETAPI_T)s->back;}
297 /**
298  *  @ingroup netapi_sched_functions
299  *  @brief netapi_sched_get_stats: API to tget NETAP scheduling context statistics
300  *
301  *  @details   API to tget NETAP scheduling context statistics
302  *  @param[in]  p_pkts TBD
303  *  @param[in]  p_cycles TBD
304  *  @param[in]  p_ccycles TBD
305  *  @retval     none
306  */
307 void netapi_sched_get_stats(unsigned long long * p_pkts, 
308                             unsigned long long * p_cycles,
309                             unsigned long long * p_ccycles);
310 #endif