Fix for SDOCM00107501:Compilation issues observed when compiling with C++
[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 #ifdef __cplusplus
51 extern "C" {
52 #endif
54 #include "netapi.h"
56 /**
57  * @brief This defines the handle to the NETAPI scheduling context.
58  * Each user space transport application thread/core should have its own
59  * scheduler context.
60  */
61 struct  NETAPI_SCHED_HANDLE_Tag;
64 /**
65  *  @ingroup netapi_cb_functions
66  *  @brief NETAPI_SCHED_CB   Callback function for scheduling context house keeping.
67  *  This allows application to set a function to be periodically called by scheduler
68  *  to perform house keeping operations. If NULL, then no callback will be invoked
69  * 
70  *  @details The application provides a callback function that the NETAPI scheduling context
71  *  will call on  a periodic/ low priority basis.
72  *  @param[in]  h   The handle to the NETAPI scheduling context
73  *  @retval     none 
74  *  @pre        @ref netapi_init
75  */
76 typedef void (*NETAPI_SCHED_CB)(struct NETAPI_SCHED_HANDLE_Tag *h);
78 /**
79  *  @ingroup sched_structures
80  *  @brief NETAPI scheduler configuration structure.
81  *
82  *  @details Pointer to this structure is passed in the call to @ref netapi_schedOpen API.
83  */
84 typedef struct NETAPI_SCHED_CONFIG_Tag
85 {
86 /**
87  * @def NETAPI_SCHED_DURATION
88  * @ingroup sched_constants
89  *      Duration configuration flag for scheduler
90  */
91 #define NETAPI_SCHED_DURATION 0x1
93 /**
94  * @def NETAPI_SCHED_CBV
95  * @ingroup sched_constants
96  *      This defines that the housekeeping call back option of scheduler context has been configured.
97  */
98 #define NETAPI_SCHED_CBV  0x2
100 /// @cond NOT_IMPLEMENTED
101 /**
102  * @def NETAPI_SCHED_POWER
103  * @ingroup sched_constants
104  *      This defines the power option of scheduler context being configured.
105  */
106 #define NETAPI_SCHED_POWER 0x4
108 /**
109  * @def NETAPI_SCHED_FINE
110  * @ingroup sched_constants
111  *      This defines the fine tune option of scheduler context being configured.
112  */
113 #define NETAPI_SCHED_FINE  0x8
114 /// @endcond
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     int             valid_flags;            /**< Flags used to configure the scheduler, @ref NETAPI_SCHED_DURATION,
123                                                  @ref NETAPI_SCHED_CBV. */
124     uint64_t        duration;               /**< Duration scheduler is configured to run, 0 == forever,
125                                                  non-zero value is ticks for scheduler to run */
126     NETAPI_SCHED_CB house_cb;               /**< House keeping callback */
128     uint32_t        interval;               /**< How many poll loop intervals after which to call the house keeping
129                                                  callback function*/
131     int             power_control;          /**< Currently NOT_IMPLEMENTED  */
134 /**
135  * @def NETAPI_SCHED_POWER_ALWAYS_OFF
136  * @ingroup sched_constants
137  *      This define is used to configure scheduler power_control option to be always off.
138  */
139 #define NETAPI_SCHED_POWER_ALWAYS_OFF 0
141 /**
142  * @def NETAPI_SCHED_POWER_ALWAYS_ON
143  * @ingroup sched_constants
144  *      This define is used to configure scheduler power_control option to be always on.
145  */
146 #define NETAPI_SCHED_POWER_ALWAYS_ON 1
149     int             idle_time;              /**< Currently NOT_IMPLEMENTED  */
150     Bool            yield;                  /**< Option to yield in scheduling loop if no packets received
151                                                  from any NETAPI PKTIO channel associated with NETAPI instance.*/
152     Bool            pollCtrlQ;              /**< Option to poll the NETCP control queues associated with the NETAPI
153                                                  intance in scheduling loop. */
154     Bool            pollGarbageQ;           /**< Option to poll the internal heaps and any application heaps that have
155                                                  been registerd with NETAPI instance. in scheduling loop. */
156 } NETAPI_SCHED_CONFIG_T;
158 /**
159  *  @ingroup sched_structures
160  *  @brief NETAPI scheduler statisics.
161  *
162  *  @details This structure is returned from call to @ref netapi_schedOpen API.
163  */
164 typedef struct NETAPI_SCHED_STATS_Tag
166     unsigned long long num_pkts;        /**< Number of packets processed in sheduler context */
167     unsigned long long busy_cycles;     /**< Number of CPU cyles scheduler was busy processing packets */
168     unsigned long long cache_cycles;    /**< Number of CPU cyles scheduler was busy in cache operations */
169 } NETAPI_SCHED_STATS_T;
171 /**
172  *  @ingroup sched_structures
173  *  @brief NETAPI scheduler configuration structure.
174  *
175  *  @details Pointer to this structure is passed in the call to @ref netapi_schedOpen API.
176  */
177 typedef struct NETAPI_SCHED_HANDLE_Tag
179 /**
180  * @def NETAPI_SCHED_STATE_CLOSE
181  * @ingroup sched_constants
182  *      This define indicates the state of the scheduler to be CLOSE state or idle
183  */
184 #define NETAPI_SCHED_STATE_CLOSE 0x0
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
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 or running
197  */
198 #define NETAPI_SCHED_STATE_OPEN 2
201     volatile int            state;              /**< @ref NETAPI_SCHED_STATE_CLOSE ,
202                                                      @ref NETAPI_SCHED_STATE_CLOSE_IN_PROGRESS ,
203                                                      @ref NETAPI_SCHED_STATE_OPEN */
204     void*                   back;               /**< Pointer back to NETAPI handle */
205     NETAPI_SCHED_CONFIG_T   config;             /**< NETAPI scheduler configuration */
206     uint64_t                start;              /**< Start time of NETAPI scheduler context */ 
207     volatile int            shutdown_reason;    /**< Currently NOT_IMPLEMENTED  */
208     volatile uint64_t       shutdown_time;      /**< Time till scheduler context will be shutdown/closed */
209     NETAPI_SCHED_STATS_T    stats;              /**< Per scheduler satistics */
210 } NETAPI_SCHED_HANDLE_T;
215 /// @cond NOT_IMPLEMENTED
216 /* return codes for sched run */
217 #define NETAPI_SCHED_RETURN_ERR         0       /**<unknown, err */
218 #define NETAPI_SCHED_RETURN_TO          1       /**<returned after timeout */
219 #define NETAPI_SCHED_RETURN_SHUTDOWN    2       /**<returned after shutdown */
220 /// @endcond
222 /**
223  *  @ingroup sched_structures
224  *  @brief NETAPI scheduler shutdown structure.
225  *  @details  This structure is passed an an argument for @ref netapi_schedClose.
226  */
227 typedef struct NETAPI_SCHED_SHUTDOWN_Tag
229 /**
230  * @def NETAPI_SCHED_SHUTDOWN_NOW
231  * @ingroup sched_constants
232  *      This define is used to shudown the scheduling context immediately 
233  */
234 #define NETAPI_SCHED_SHUTDOWN_NOW 0
236 /// @cond NOT_IMPLEMENTED
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.
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
250 /// @endcond
251     int shutdown_type;                      /**< @ref NETAPI_SCHED_SHUTDOWN_NOW*/
253     int timeout;                            /**< Currently NOT_IMPLEMENTED  */
254 } NETAPI_SCHED_SHUTDOWN_T;
256 /**
257  *  @ingroup sched_functions
258  *  @brief netapi_schedOpen: API to open a scheduling context.
259  *
260  *  @details API to open a scheduling context.
261  *  @param[in]  n   the NETAPI handle, @ref NETAPI_T
262  *  @param[in] p_config :pointer to @ref NETAPI_SCHED_CONFIG_T
263   *  @param[out] p_err    Pointer to error code.
264  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
265  *  @pre        @ref netapi_init 
266  */
267 NETAPI_SCHED_HANDLE_T * netapi_schedOpen(NETAPI_T                   n,
268                                          NETAPI_SCHED_CONFIG_T*     p_config,
269                                          int*                       p_err);
271 /// @cond NOT_IMPLEMENTED
272 /**
273  *  @ingroup sched_functions
274  *  @brief netapi_schedControl: API to re-configure a scheduling context.
275  *
276  *  @details API to re-configure a scheduling context.
277  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
278  *  @param[in] p_config     Pointer to @ref NETAPI_SCHED_CONFIG_T
279  *  @param[out] p_err    Pointer to error code.
280  *  @retval     Handle associated with created scheduler context, @ref NETAPI_SCHED_HANDLE_T
281  *  @pre        @ref netapi_schedOpen 
282  */
283 int netapi_schedControl(NETAPI_SCHED_HANDLE_T*  s,
284                         NETAPI_SCHED_CONFIG_T*  p_config,
285                         int*                    p_err);
286 /// @endcond
288 /**
289  *  @ingroup sched_functions
290  *  @brief netapi_schedRun: API for main entry point to scheduler.
291  *
292  *  @details API for main entry point to scheduler. User application gives up control to scheduler.
293   *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
294  *  @param[out] p_err: error code, zero on sucess, non-zero on failure
295  *  @retval     always 1
296  *  @pre        @ref netapi_schedOpen 
297  */
298 int netapi_schedRun(NETAPI_SCHED_HANDLE_T*  s,
299                     int*                    p_err);
301 /**
302  *  @ingroup sched_functions
303  *  @brief netapi_schedClose: API to close a scheduling context.
304  *
305  *  @details API to close a scheduling context.
306  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
307  *  @param[in]  p_close  @ref NETAPI_SCHED_SHUTDOWN_T
308  *  @param[out] p_err    Pointer to error code.
309  *  @retval     NO USED, ALWAYS 1
310  *  @pre        @ref netapi_schedOpen 
311  */
312 int netapi_schedClose(NETAPI_SCHED_HANDLE_T*    s, 
313                       NETAPI_SCHED_SHUTDOWN_T*  p_close,
314                       int*                      p_err);
316 /**
317  *  @ingroup sched_functions
318  *  @brief netapi_schedGetHandle: API to get the NETAPI handle from scheduling context.
319  *
320  *  @details API to get the NETAPI handle from scheduling context.
321  *  @param[in]  s The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
322  *  @retval     Handle to NETAPI instance
323  */
324 static NETAPI_T netapi_schedGetHandle(NETAPI_SCHED_HANDLE_T *s)
326     return (NETAPI_T)s->back;
329 /**
330  *  @ingroup sched_functions
331  *  @brief netapi_schedGetStats: API to get scheduling context statistics.
332  *
333  *  @details API to get scheduling context statistics.
334  *  @param[in]  s           The NETAPI scheduling context handle, @ref NETAPI_SCHED_HANDLE_T
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_schedGetStats(NETAPI_SCHED_HANDLE_T*    s,
341                           unsigned long long*       p_pkts, 
342                           unsigned long long*       p_cycles,
343                           unsigned long long*       p_ccycles);
345 #ifdef __cplusplus
347 #endif
349 #endif