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
165 {
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
221 {
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)
323 {
324 return (NETAPI_T)s->back;
325 }
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