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