4cc3ed9942b6c32cec00be3823facb06a09c1706
[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  scheduler header file for  user space transport library
7  *
8  * REVISION HISTORY:
9  *
10  *  Copyright (c) Texas Instruments Incorporated 2013
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  */
42 /**
43  *  @file netapi_sched.h
44  *  @brief netapi scheduler header file for user space transport library
45  */
48 #ifndef __NETAPI_SCHED__
49 #define __NETAPI_SCHED__
50 #include "netapi.h"
52 /**
53  * @brief This defines the handle to the NETAPI scheduling context.
54  * Each user space transport application thread/core should have its own
55  * scheduler context.
56  */
57 struct  NETAPI_SCHED_HANDLE_Tag;
60 /**
61  *  @ingroup netapi_cb_functions
62  *  @brief NETAPI_SCHED_CB   Callback function for scheduling context house keeping.
63  *  This allows application to set a function to be periodically called by scheduler
64  *  to perform house keeping operations. If NULL, then no callback will be invoked
65  * 
66  *  @details The application provides a callback function that the NETAPI scheduling context
67  *  will call on  a periodic/ low priority basis.
68  *  @param[in]  h   The handle to the NETAPI scheduling context
69  *  @retval     none 
70  *  @pre        @ref netapi_init
71  */
72 typedef void (*NETAPI_SCHED_CB)(struct NETAPI_SCHED_HANDLE_Tag *h);
74 /**
75  *  @ingroup sched_structures
76  *  @brief NETAPI scheduler configuration structure.
77  *
78  *  @details Pointer to this structure is passed in the call to @ref netapi_schedOpen API.
79  */
80 typedef struct NETAPI_SCHED_CONFIG_Tag
81 {
82 /**
83  * @def NETAPI_SCHED_DURATION
84  * @ingroup sched_constants
85  *      Duration configuration flag for scheduler
86  */
87 #define NETAPI_SCHED_DURATION 0x1
89 /**
90  * @def NETAPI_SCHED_CBV
91  * @ingroup sched_constants
92  *      This defines that the housekeeping call back option of scheduler context has been configured.
93  */
94 #define NETAPI_SCHED_CBV  0x2
96 /// @cond NOT_IMPLEMENTED
97 /**
98  * @def NETAPI_SCHED_POWER
99  * @ingroup sched_constants
100  *      This defines the power option of scheduler context being configured.
101  */
102 #define NETAPI_SCHED_POWER 0x4
104 /**
105  * @def NETAPI_SCHED_FINE
106  * @ingroup sched_constants
107  *      This defines the fine tune option of scheduler context being configured.
108  */
109 #define NETAPI_SCHED_FINE  0x8
110 /// @endcond
111 /**
112  * @def NETAPI_SCHED_FOREVER
113  * @ingroup sched_constants
114  *      This defines is used to configure scheduler to run forever.
115  */
116 #define NETAPI_SCHED_FOREVER 0L
118     int             valid_flags;            /**< Flags used to configure the scheduler, @ref NETAPI_SCHED_DURATION,
119                                                  @ref NETAPI_SCHED_CBV. */
120     uint64_t        duration;               /**< Duration scheduler is configured to run, 0 == forever,
121                                                  non-zero value is ticks for scheduler to run */
122     NETAPI_SCHED_CB house_cb;               /**< House keeping callback */
124     uint32_t        interval;               /**< How many poll loop intervals after which to call the house keeping
125                                                  callback function*/
127     int             power_control;          /**< Currently NOT_IMPLEMENTED  */
130 /**
131  * @def NETAPI_SCHED_POWER_ALWAYS_OFF
132  * @ingroup sched_constants
133  *      This define is used to configure scheduler power_control option to be always off.
134  */
135 #define NETAPI_SCHED_POWER_ALWAYS_OFF 0
137 /**
138  * @def NETAPI_SCHED_POWER_ALWAYS_ON
139  * @ingroup sched_constants
140  *      This define is used to configure scheduler power_control option to be always on.
141  */
142 #define NETAPI_SCHED_POWER_ALWAYS_ON 1
145     int             idle_time;              /**< Currently NOT_IMPLEMENTED  */
146     Bool            yield;                  /**< Option to yield in scheduling loop if no packets received
147                                                  from any NETAPI PKTIO channel associated with NETAPI instance.*/
148     Bool            pollCtrlQ;              /**< Option to poll the NETCP control queues associated with the NETAPI
149                                                  intance in scheduling loop. */
150     Bool            pollGarbageQ;           /**< Option to poll the internal heaps and any application heaps that have
151                                                  been registerd with NETAPI instance. in scheduling loop. */
152 } NETAPI_SCHED_CONFIG_T;
154 /**
155  *  @ingroup sched_structures
156  *  @brief NETAPI scheduler statisics.
157  *
158  *  @details This structure is returned from call to @ref netapi_schedOpen API.
159  */
160 typedef struct NETAPI_SCHED_STATS_Tag
162     unsigned long long num_pkts;        /**< Number of packets processed in sheduler context */
163     unsigned long long busy_cycles;     /**< Number of CPU cyles scheduler was busy processing packets */
164     unsigned long long cache_cycles;    /**< Number of CPU cyles scheduler was busy in cache operations */
165 } NETAPI_SCHED_STATS_T;
167 /**
168  *  @ingroup sched_structures
169  *  @brief NETAPI scheduler configuration structure.
170  *
171  *  @details Pointer to this structure is passed in the call to @ref netapi_schedOpen API.
172  */
173 typedef struct NETAPI_SCHED_HANDLE_Tag
175 /**
176  * @def NETAPI_SCHED_STATE_CLOSE
177  * @ingroup sched_constants
178  *      This define indicates the state of the scheduler to be CLOSE state or idle
179  */
180 #define NETAPI_SCHED_STATE_CLOSE 0x0
182 /**
183  * @def NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS
184  * @ingroup sched_constants
185  *      This define indicates the state of the scheduler is being shutdown state
186  */
187 #define NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS 1
189 /**
190  * @def NETAPI_SCHED_STATE_OPEN
191  * @ingroup sched_constants
192  *      This define indicates the state of the scheduler is OPEN or running
193  */
194 #define NETAPI_SCHED_STATE_OPEN 2
197     volatile int            state;              /**< @ref NETAPI_SCHED_STATE_CLOSE ,
198                                                      @ref NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS ,
199                                                      @ref NETAPI_SCHED_STATE_OPEN */
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 */ 
203     volatile int            shutdown_reason;    /**< Currently NOT_IMPLEMENTED  */
204     volatile uint64_t       shutdown_time;      /**< Time till scheduler context will be shutdown/closed */
205     NETAPI_SCHED_STATS_T    stats;              /**< Per scheduler satistics */
206 } NETAPI_SCHED_HANDLE_T;
211 /// @cond NOT_IMPLEMENTED
212 /* return codes for sched run */
213 #define NETAPI_SCHED_RETURN_ERR         0       /**<unknown, err */
214 #define NETAPI_SCHED_RETURN_TO          1       /**<returned after timeout */
215 #define NETAPI_SCHED_RETURN_SHUTDOWN    2       /**<returned after shutdown */
216 /// @endcond
218 /**
219  *  @ingroup sched_structures
220  *  @brief NETAPI scheduler shutdown structure.
221  *  @details  This structure is passed an an argument for @ref netapi_schedClose.
222  */
223 typedef struct NETAPI_SCHED_SHUTDOWN_Tag
225 /**
226  * @def NETAPI_SCHED_SHUTDOWN_NOW
227  * @ingroup sched_constants
228  *      This define is used to shudown the scheduling context immediately 
229  */
230 #define NETAPI_SCHED_SHUTDOWN_NOW 0
232 /// @cond NOT_IMPLEMENTED
233 /**
234  * @def NETAPI_SCHED_SHUTDOWN_TO
235  * @ingroup sched_constants
236  *      This define is used to shudown the scheduling context after a short while.
237  */
238 #define NETAPI_SCHED_SHUTDOWN_TO  1
240 /**
241  * @def NETAPI_SCHED_SHUTDOWN_NEXT_IDLE
242  * @ingroup sched_constants
243  *      This define is used to shudown the scheduling context during next idle period
244  */
245 #define NETAPI_SCHED_SHUTDOWN_NEXT_IDLE  2
246 /// @endcond
247     int shutdown_type;                      /**< @ref NETAPI_SCHED_SHUTDOWN_NOW*/
249     int timeout;                            /**< Currently NOT_IMPLEMENTED  */
250 } NETAPI_SCHED_SHUTDOWN_T;
252 /**
253  *  @ingroup sched_functions
254  *  @brief netapi_schedOpen: API to open a scheduling context.
255  *
256  *  @details API to open a scheduling context.
257  *  @param[in]  n   the NETAPI handle, @ref NETAPI_T
258  *  @param[in] p_config :pointer to @ref NETAPI_SCHED_CONFIG_T
259   *  @param[out] p_err    Pointer to error code.
260  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
261  *  @pre        @ref netapi_init 
262  */
263 NETAPI_SCHED_HANDLE_T * netapi_schedOpen(NETAPI_T                   n,
264                                          NETAPI_SCHED_CONFIG_T*     p_config,
265                                          int*                       p_err);
267 /// @cond NOT_IMPLEMENTED
268 /**
269  *  @ingroup sched_functions
270  *  @brief netapi_schedControl: API to re-configure a scheduling context.
271  *
272  *  @details API to re-configure a scheduling context.
273  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
274  *  @param[in] p_config     Pointer to @ref NETAPI_SCHED_CONFIG_T
275  *  @param[out] p_err    Pointer to error code.
276  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
277  *  @pre        @ref netapi_schedOpen 
278  */
279 int netapi_schedControl(NETAPI_SCHED_HANDLE_T*  s,
280                         NETAPI_SCHED_CONFIG_T*  p_config,
281                         int*                    p_err);
282 /// @endcond
284 /**
285  *  @ingroup sched_functions
286  *  @brief netapi_schedRun: API for main entry point to scheduler.
287  *
288  *  @details API for main entry point to scheduler. User application gives up control to scheduler.
289   *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
290  *  @param[out] p_err: error code, zero on sucess, non-zero on failure
291  *  @retval     always 1
292  *  @pre        @ref netapi_schedOpen 
293  */
294 int netapi_schedRun(NETAPI_SCHED_HANDLE_T*  s,
295                     int*                    p_err);
297 /**
298  *  @ingroup sched_functions
299  *  @brief netapi_schedClose: API to close a scheduling context.
300  *
301  *  @details API to close a scheduling context.
302  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
303  *  @param[in]  p_close  @ref NETAPI_SCHED_SHUTDOWN_T
304  *  @param[out] p_err    Pointer to error code.
305  *  @retval     NO USED, ALWAYS 1
306  *  @pre        @ref netapi_schedOpen 
307  */
308 int netapi_schedClose(NETAPI_SCHED_HANDLE_T*    s, 
309                       NETAPI_SCHED_SHUTDOWN_T*  p_close,
310                       int*                      p_err);
312 /**
313  *  @ingroup sched_functions
314  *  @brief netapi_schedGetHandle: API to get the NETAPI handle from scheduling context.
315  *
316  *  @details API to get the NETAPI handle from scheduling context.
317  *  @param[in]  s The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
318  *  @retval     Handle to NETAPI instance
319  */
320 static NETAPI_T netapi_schedGetHandle(NETAPI_SCHED_HANDLE_T *s)
322     return (NETAPI_T)s->back;
325 /**
326  *  @ingroup sched_functions
327  *  @brief netapi_schedGetStats: API to get scheduling context statistics.
328  *
329  *  @details API to get scheduling context statistics.
330  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
331  *  @param[in]  p_pkts  total number of packets processed by scheduler poll loop
332  *  @param[in]  p_cycles total number cycles taken by scheduler poll loop
333  *  @param[in]  p_ccycles  total number of cache control cycles taken by scheduler poll loop
334  *  @retval     none
335  */
336 void netapi_schedGetStats(NETAPI_SCHED_HANDLE_T*    s,
337                           unsigned long long*       p_pkts, 
338                           unsigned long long*       p_cycles,
339                           unsigned long long*       p_ccycles);
340 #endif