cpu/ixp/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  * Redistribution and use in source and binary forms, with or without
  26  * modification, are permitted provided that the following conditions
  27  * are met:
  28  * 1. Redistributions of source code must retain the above copyright
  29  *    notice, this list of conditions and the following disclaimer.
  30  * 2. Redistributions in binary form must reproduce the above copyright
  31  *    notice, this list of conditions and the following disclaimer in the
  32  *    documentation and/or other materials provided with the distribution.
  33  * 3. Neither the name of the Intel Corporation nor the names of its contributors
  34  *    may be used to endorse or promote products derived from this software
  35  *    without specific prior written permission.
  36  *
  37  * @par
  38  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
  39  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  41  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
  42  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  43  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  44  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  45  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  46  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  47  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  48  * SUCH DAMAGE.
  49  *
  50  * @par
  51  * -- End of Copyright Notice --
  52 */
  53
  54 /**
  55  * @defgroup IxTimerCtrl IXP400 Timer Control (IxTimerCtrl) API
  56  *
  57  * @brief The public API for the IXP400 Timer Control Component.
  58  *
  59  * @{
  60  */
  61
  62 #ifndef IxTimerCtrl_H
  63 #define IxTimerCtrl_H
  64
  65
  66 #include "IxTypes.h"
  67 /* #include "Ossl.h" */
  68
  69 /*
  70  * #defines and macros used in this file.
  71  */
  72
  73 /**
  74  * @ingroup IxTimerCtrl
  75  *
  76  * @def IX_TIMERCTRL_NO_FREE_TIMERS
  77  *
  78  * @brief Timer schedule return code.
  79  *
  80  * Indicates that the request to start a timer failed because
  81  * all available timer resources are used.
  82  */
  83 #define IX_TIMERCTRL_NO_FREE_TIMERS 2
  84
  85
  86 /**
  87  * @ingroup IxTimerCtrl
  88  *
  89  * @def IX_TIMERCTRL_PARAM_ERROR
  90  *
  91  * @brief Timer schedule return code.
  92  *
  93  * Indicates that the request to start a timer failed because
  94  * the client has supplied invalid parameters.
  95  */
  96 #define IX_TIMERCTRL_PARAM_ERROR 3
  97
  98
  99 /*
 100  * Typedefs whose scope is limited to this file.
 101  */
 102
 103 /**
 104  * @ingroup IxTimerCtrl
 105  *
 106  * @brief A typedef for a pointer to a timer callback function.
 107  * @para void * - This parameter is supplied by the client when the
 108  * timer is started and passed back to the client in the callback.
 109  * @note in general timer callback functions should not block or
 110  * take longer than 100ms. This constraint is required to ensure that
 111  * higher priority callbacks are not held up.
 112  * All callbacks are called from the same thread.
 113  * This thread is a shared resource.
 114  * The parameter passed is provided when the timer is scheduled.
 115  */
 116 typedef void (*IxTimerCtrlTimerCallback)(void *userParam);
 117
 118
 119 /**
 120  * @ingroup IxTimerCtrl
 121  *
 122  * @brief List used to identify the users of timers.
 123  * @note The order in this list indicates priority.  Components appearing
 124  * higher in the list will be given priority over components lower in the
 125  * list.  When adding components, please insert at an appropriate position
 126  * for priority ( i.e values should be less than IxTimerCtrlMaxPurpose ) .
 127  */
 128 typedef enum
 129 {
 130     IxTimerCtrlAdslPurpose,
 131    /* Insert new purposes above this line only
 132     */
 133    IxTimerCtrlMaxPurpose
 134 }
 135 IxTimerCtrlPurpose;
 136
 137
 138 /*
 139  * Function definition
 140  */
 141
 142 /**
 143  * @ingroup IxTimerCtrl
 144  *
 145  * @fn ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,
 146                        void *userParam,
 147                        IxTimerCtrlPurpose purpose,
 148                        UINT32 relativeTime,
 149                        unsigned *timerId )
 150  *
 151  * @brief Schedules a callback function to be called after a period of "time".
 152  * The callback function should not block or run for more than 100ms.
 153  * This function
 154  *
 155  * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called.
 156  * @param userParam void [in] - a parameter to send to the callback function, can be NULL.
 157  * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will
 158  * decide the priority of callbacks with different purpose.
 159  * @param relativeTime UINT32 [in] - time relative to now in milliseconds after which the callback
 160  * will be called. The time must be greater than the duration of one OS tick.
 161  * @param *timerId unsigned [out] -  An id for the callback scheduled.
 162  * This id can be used to cancel the callback.
 163  * @return
 164  * @li IX_SUCCESS - The timer was started successfully.
 165  * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number
 166  * of running timers has been exceeded.
 167  * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied
 168  * a NULL callback func, or the requested timeout is less than one OS tick.
 169  * @note  This function is re-entrant. The function accesses a list of running timers
 170  * and may suspend the calling thread if this list is being accesed by another thread.
 171  */
 172 PUBLIC IX_STATUS
 173 ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,
 174                        void *userParam,
 175                        IxTimerCtrlPurpose purpose,
 176                        UINT32 relativeTime,
 177                        unsigned *timerId );
 178
 179
 180 /**
 181  * @ingroup IxTimerCtrl
 182  *
 183  * @fn ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,
 184                                 void *param,
 185                                 IxTimerCtrlPurpose purpose,
 186                                 UINT32 interval,
 187                                 unsigned *timerId )
 188  *
 189  * @brief Schedules a callback function to be called after a period of "time".
 190  * The callback function should not block or run for more than 100ms.
 191  *
 192  * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called.
 193  * @param userParam void [in] - a parameter to send to the callback function, can be NULL.
 194  * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will
 195  * decide the priority of callbacks with different purpose.
 196  * @param interval UINT32 [in] - the interval in milliseconds between calls to func.
 197  * @param timerId unsigned [out] - An id for the callback scheduled.
 198  * This id can be used to cancel the callback.
 199  * @return
 200  * @li IX_SUCCESS - The timer was started successfully.
 201  * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number
 202  * of running timers has been exceeded.
 203  * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied
 204  * a NULL callback func, or the requested timeout is less than one OS tick.
 205  * @note  This function is re-entrant. The function accesses a list of running timers
 206  * and may suspend the calling thread if this list is being accesed by another thread.
 207  */
 208 PUBLIC IX_STATUS
 209 ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,
 210                                 void *param,
 211                                 IxTimerCtrlPurpose purpose,
 212                                 UINT32 interval,
 213                                 unsigned *timerId );
 214
 215 /**
 216  * @ingroup IxTimerCtrl
 217  *
 218  * @fn ixTimerCtrlCancel (unsigned id)
 219  *
 220  * @brief Cancels a scheduled callback.
 221  *
 222  * @param id unsigned [in] - the id of the callback to be cancelled.
 223  * @return
 224  * @li IX_SUCCESS - The timer was successfully stopped.
 225  * @li IX_FAIL - The id parameter did not corrrespond to any running timer..
 226  * @note This function is re-entrant. The function accesses a list of running timers
 227  * and may suspend the calling thread if this list is being accesed by another thread.
 228  */
 229 PUBLIC IX_STATUS
 230 ixTimerCtrlCancel (unsigned id);
 231
 232 /**
 233  * @ingroup IxTimerCtrl
 234  *
 235  * @fn ixTimerCtrlInit(void)
 236  *
 237  * @brief Initialise the Timer Control Component.
 238  * @return
 239  * @li IX_SUCCESS - The timer control component initialized successfully.
 240  * @li IX_FAIL - The timer control component initialization failed,
 241  * or the component was already initialized.
 242  * @note This must be done before any other API function is called.
 243  * This function should be called once only and is not re-entrant.
 244  */
 245 PUBLIC IX_STATUS
 246 ixTimerCtrlInit(void);
 247
 248
 249 /**
 250  * @ingroup IxTimerCtrl
 251  *
 252  * @fn ixTimerCtrlShow( void )
 253  *
 254  * @brief Display the status of the Timer Control Component.
 255  * @return void
 256  * @note Displays a list of running timers.
 257  * This function is not re-entrant. This function does not suspend the calling thread.
 258  */
 259 PUBLIC void
 260 ixTimerCtrlShow( void );
 261
 262 #endif  /* IXTIMERCTRL_H */
 263