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
169 {
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
228 {
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)
330 {
331 return (NETAPI_T)s->back;
332 }
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