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  */
  41
  42 /**
  43  *  @file netapi_sched.h
  44  *  @brief netapi scheduler header file for user space transport library
  45  */
  46
  47
  48 #ifndef __NETAPI_SCHED__
  49 #define __NETAPI_SCHED__
  50 #include "netapi.h"
  51
  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;
  58
  59
  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);
  73
  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
  88
  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
  95
  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
 103
 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
 117
 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 */
 123
 124     uint32_t        interval;               /**< How many poll loop intervals after which to call the house keeping
 125                                                  callback function*/
 126
 127     int             power_control;          /**< Currently NOT_IMPLEMENTED  */
 128
 129
 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
 136
 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
 143
 144
 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;
 153
 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
 161 {
 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;
 166
 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
 174 {
 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
 181
 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
 188
 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
 195
 196
 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;
 207
 208
 209
 210
 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
 217
 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
 224 {
 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
 231
 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
 239
 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*/
 248
 249     int timeout;                            /**< Currently NOT_IMPLEMENTED  */
 250 } NETAPI_SCHED_SHUTDOWN_T;
 251
 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);
 266
 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
 283
 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);
 296
 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);
 311
 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)
 321 {
 322     return (NETAPI_T)s->back;
 323 }
 324
 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