drivers/net/npe/include/IxTimerCtrl.h

   1 /**
   2  * @file IxTimerCtrl.h
   3  * @brief
   4  *    This is the header file for the Timer Control component.
   5  *
   6  *    The timer callback control component provides a mechanism by which different
   7  *    client components can start a timer and have a supplied callback function
   8  *    invoked when the timer expires.
   9  *    The callbacks are all dispatched from one thread inside this component.
  10  *    Any component that needs to be called periodically should use this facility
  11  *    rather than create its own task with a sleep loop.
  12  *
  13  * @par
  14  *
  15  * @par
  16  * IXP400 SW Release version 2.0
  17  *
  18  * -- Copyright Notice --
  19  *
  20  * @par
  21  * Copyright 2001-2005, Intel Corporation.
  22  * All rights reserved.
  23  *
  24  * @par
  25  * SPDX-License-Identifier:     BSD-3-Clause
  26  * @par
  27  * -- End of Copyright Notice --
  28 */
  29
  30 /**
  31  * @defgroup IxTimerCtrl IXP400 Timer Control (IxTimerCtrl) API
  32  *
  33  * @brief The public API for the IXP400 Timer Control Component.
  34  *
  35  * @{
  36  */
  37
  38 #ifndef IxTimerCtrl_H
  39 #define IxTimerCtrl_H
  40
  41
  42 #include "IxTypes.h"
  43 /* #include "Ossl.h" */
  44
  45 /*
  46  * #defines and macros used in this file.
  47  */
  48
  49 /**
  50  * @ingroup IxTimerCtrl
  51  *
  52  * @def IX_TIMERCTRL_NO_FREE_TIMERS
  53  *
  54  * @brief Timer schedule return code.
  55  *
  56  * Indicates that the request to start a timer failed because
  57  * all available timer resources are used.
  58  */
  59 #define IX_TIMERCTRL_NO_FREE_TIMERS 2
  60
  61
  62 /**
  63  * @ingroup IxTimerCtrl
  64  *
  65  * @def IX_TIMERCTRL_PARAM_ERROR
  66  *
  67  * @brief Timer schedule return code.
  68  *
  69  * Indicates that the request to start a timer failed because
  70  * the client has supplied invalid parameters.
  71  */
  72 #define IX_TIMERCTRL_PARAM_ERROR 3
  73
  74
  75 /*
  76  * Typedefs whose scope is limited to this file.
  77  */
  78
  79 /**
  80  * @ingroup IxTimerCtrl
  81  *
  82  * @brief A typedef for a pointer to a timer callback function.
  83  * @para void * - This parameter is supplied by the client when the
  84  * timer is started and passed back to the client in the callback.
  85  * @note in general timer callback functions should not block or
  86  * take longer than 100ms. This constraint is required to ensure that
  87  * higher priority callbacks are not held up.
  88  * All callbacks are called from the same thread.
  89  * This thread is a shared resource.
  90  * The parameter passed is provided when the timer is scheduled.
  91  */
  92 typedef void (*IxTimerCtrlTimerCallback)(void *userParam);
  93
  94
  95 /**
  96  * @ingroup IxTimerCtrl
  97  *
  98  * @brief List used to identify the users of timers.
  99  * @note The order in this list indicates priority.  Components appearing
 100  * higher in the list will be given priority over components lower in the
 101  * list.  When adding components, please insert at an appropriate position
 102  * for priority ( i.e values should be less than IxTimerCtrlMaxPurpose ) .
 103  */
 104 typedef enum
 105 {
 106     IxTimerCtrlAdslPurpose,
 107    /* Insert new purposes above this line only
 108     */
 109    IxTimerCtrlMaxPurpose
 110 }
 111 IxTimerCtrlPurpose;
 112
 113
 114 /*
 115  * Function definition
 116  */
 117
 118 /**
 119  * @ingroup IxTimerCtrl
 120  *
 121  * @fn ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,
 122                        void *userParam,
 123                        IxTimerCtrlPurpose purpose,
 124                        UINT32 relativeTime,
 125                        unsigned *timerId )
 126  *
 127  * @brief Schedules a callback function to be called after a period of "time".
 128  * The callback function should not block or run for more than 100ms.
 129  * This function
 130  *
 131  * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called.
 132  * @param userParam void [in] - a parameter to send to the callback function, can be NULL.
 133  * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will
 134  * decide the priority of callbacks with different purpose.
 135  * @param relativeTime UINT32 [in] - time relative to now in milliseconds after which the callback
 136  * will be called. The time must be greater than the duration of one OS tick.
 137  * @param *timerId unsigned [out] -  An id for the callback scheduled.
 138  * This id can be used to cancel the callback.
 139  * @return
 140  * @li IX_SUCCESS - The timer was started successfully.
 141  * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number
 142  * of running timers has been exceeded.
 143  * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied
 144  * a NULL callback func, or the requested timeout is less than one OS tick.
 145  * @note  This function is re-entrant. The function accesses a list of running timers
 146  * and may suspend the calling thread if this list is being accesed by another thread.
 147  */
 148 PUBLIC IX_STATUS
 149 ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,
 150                        void *userParam,
 151                        IxTimerCtrlPurpose purpose,
 152                        UINT32 relativeTime,
 153                        unsigned *timerId );
 154
 155
 156 /**
 157  * @ingroup IxTimerCtrl
 158  *
 159  * @fn ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,
 160                                 void *param,
 161                                 IxTimerCtrlPurpose purpose,
 162                                 UINT32 interval,
 163                                 unsigned *timerId )
 164  *
 165  * @brief Schedules a callback function to be called after a period of "time".
 166  * The callback function should not block or run for more than 100ms.
 167  *
 168  * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called.
 169  * @param userParam void [in] - a parameter to send to the callback function, can be NULL.
 170  * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will
 171  * decide the priority of callbacks with different purpose.
 172  * @param interval UINT32 [in] - the interval in milliseconds between calls to func.
 173  * @param timerId unsigned [out] - An id for the callback scheduled.
 174  * This id can be used to cancel the callback.
 175  * @return
 176  * @li IX_SUCCESS - The timer was started successfully.
 177  * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number
 178  * of running timers has been exceeded.
 179  * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied
 180  * a NULL callback func, or the requested timeout is less than one OS tick.
 181  * @note  This function is re-entrant. The function accesses a list of running timers
 182  * and may suspend the calling thread if this list is being accesed by another thread.
 183  */
 184 PUBLIC IX_STATUS
 185 ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,
 186                                 void *param,
 187                                 IxTimerCtrlPurpose purpose,
 188                                 UINT32 interval,
 189                                 unsigned *timerId );
 190
 191 /**
 192  * @ingroup IxTimerCtrl
 193  *
 194  * @fn ixTimerCtrlCancel (unsigned id)
 195  *
 196  * @brief Cancels a scheduled callback.
 197  *
 198  * @param id unsigned [in] - the id of the callback to be cancelled.
 199  * @return
 200  * @li IX_SUCCESS - The timer was successfully stopped.
 201  * @li IX_FAIL - The id parameter did not corrrespond to any running timer..
 202  * @note This function is re-entrant. The function accesses a list of running timers
 203  * and may suspend the calling thread if this list is being accesed by another thread.
 204  */
 205 PUBLIC IX_STATUS
 206 ixTimerCtrlCancel (unsigned id);
 207
 208 /**
 209  * @ingroup IxTimerCtrl
 210  *
 211  * @fn ixTimerCtrlInit(void)
 212  *
 213  * @brief Initialise the Timer Control Component.
 214  * @return
 215  * @li IX_SUCCESS - The timer control component initialized successfully.
 216  * @li IX_FAIL - The timer control component initialization failed,
 217  * or the component was already initialized.
 218  * @note This must be done before any other API function is called.
 219  * This function should be called once only and is not re-entrant.
 220  */
 221 PUBLIC IX_STATUS
 222 ixTimerCtrlInit(void);
 223
 224
 225 /**
 226  * @ingroup IxTimerCtrl
 227  *
 228  * @fn ixTimerCtrlShow( void )
 229  *
 230  * @brief Display the status of the Timer Control Component.
 231  * @return void
 232  * @note Displays a list of running timers.
 233  * This function is not re-entrant. This function does not suspend the calling thread.
 234  */
 235 PUBLIC void
 236 ixTimerCtrlShow( void );
 237
 238 #endif  /* IXTIMERCTRL_H */
 239