/**  * @file IxTimerCtrl.h * @brief  *    This is the header file for the Timer Control component. * *    The timer callback control component provides a mechanism by which different  *    client components can start a timer and have a supplied callback function *    invoked when the timer expires. *    The callbacks are all dispatched from one thread inside this component.  *    Any component that needs to be called periodically should use this facility  *    rather than create its own task with a sleep loop.  * * @par *  * @par * IXP400 SW Release version 2.0 *  * -- Copyright Notice -- *  * @par * Copyright 2001-2005, Intel Corporation. * All rights reserved. *  * @par * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright *    notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright *    notice, this list of conditions and the following disclaimer in the *    documentation and/or other materials provided with the distribution. * 3. Neither the name of the Intel Corporation nor the names of its contributors *    may be used to endorse or promote products derived from this software *    without specific prior written permission. *  * @par * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. *  * @par * -- End of Copyright Notice --*//** * @defgroup IxTimerCtrl IXP400 Timer Control (IxTimerCtrl) API * * @brief The public API for the IXP400 Timer Control Component. * * @{ */#ifndef IxTimerCtrl_H#define IxTimerCtrl_H#include "IxTypes.h"/* #include "Ossl.h" *//* * #defines and macros used in this file. *//** * @ingroup IxTimerCtrl * * @def IX_TIMERCTRL_NO_FREE_TIMERS * * @brief Timer schedule return code. * * Indicates that the request to start a timer failed because * all available timer resources are used.  */#define IX_TIMERCTRL_NO_FREE_TIMERS 2/** * @ingroup IxTimerCtrl * * @def IX_TIMERCTRL_PARAM_ERROR * * @brief Timer schedule return code. * * Indicates that the request to start a timer failed because * the client has supplied invalid parameters. */#define IX_TIMERCTRL_PARAM_ERROR 3 /* * Typedefs whose scope is limited to this file. *//** * @ingroup IxTimerCtrl * * @brief A typedef for a pointer to a timer callback function.  * @para void * - This parameter is supplied by the client when the * timer is started and passed back to the client in the callback. * @note in general timer callback functions should not block or  * take longer than 100ms. This constraint is required to ensure that * higher priority callbacks are not held up.  * All callbacks are called from the same thread.  * This thread is a shared resource.  * The parameter passed is provided when the timer is scheduled. */typedef void (*IxTimerCtrlTimerCallback)(void *userParam);/** * @ingroup IxTimerCtrl * * @brief List used to identify the users of timers. * @note The order in this list indicates priority.  Components appearing  * higher in the list will be given priority over components lower in the * list.  When adding components, please insert at an appropriate position * for priority ( i.e values should be less than IxTimerCtrlMaxPurpose ) . */typedef enum {    IxTimerCtrlAdslPurpose,   /* Insert new purposes above this line only    */   IxTimerCtrlMaxPurpose}IxTimerCtrlPurpose;/* * Function definition *//** * @ingroup IxTimerCtrl * * @fn ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,                        void *userParam,                        IxTimerCtrlPurpose purpose,	               UINT32 relativeTime,                       unsigned *timerId ) *  * @brief Schedules a callback function to be called after a period of "time". * The callback function should not block or run for more than 100ms. * This function  * * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called. * @param userParam void [in] - a parameter to send to the callback function, can be NULL. * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will  * decide the priority of callbacks with different purpose. * @param relativeTime UINT32 [in] - time relative to now in milliseconds after which the callback  * will be called. The time must be greater than the duration of one OS tick. * @param *timerId unsigned [out] -  An id for the callback scheduled.  * This id can be used to cancel the callback. * @return  * @li IX_SUCCESS - The timer was started successfully. * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number * of running timers has been exceeded. * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied  * a NULL callback func, or the requested timeout is less than one OS tick. * @note  This function is re-entrant. The function accesses a list of running timers * and may suspend the calling thread if this list is being accesed by another thread. */PUBLIC IX_STATUS ixTimerCtrlSchedule(IxTimerCtrlTimerCallback func,                        void *userParam,                        IxTimerCtrlPurpose purpose,	               UINT32 relativeTime,                       unsigned *timerId );/** * @ingroup IxTimerCtrl * * @fn ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,                                 void *param,                                 IxTimerCtrlPurpose purpose,			        UINT32 interval,                                unsigned *timerId ) *  * @brief Schedules a callback function to be called after a period of "time". * The callback function should not block or run for more than 100ms. * * @param func @ref IxTimerCtrlTimerCallback [in] - the callback function to be called. * @param userParam void [in] - a parameter to send to the callback function, can be NULL. * @param purpose @ref IxTimerCtrlPurpose [in] - the purpose of the callback, internally this component will  * decide the priority of callbacks with different purpose. * @param interval UINT32 [in] - the interval in milliseconds between calls to func.  * @param timerId unsigned [out] - An id for the callback scheduled.  * This id can be used to cancel the callback. * @return  * @li IX_SUCCESS - The timer was started successfully. * @li IX_TIMERCTRL_NO_FREE_TIMERS - The timer was not started because the maximum number * of running timers has been exceeded. * @li IX_TIMERCTRL_PARAM_ERROR - The timer was not started because the client has supplied  * a NULL callback func, or the requested timeout is less than one OS tick. * @note  This function is re-entrant. The function accesses a list of running timers * and may suspend the calling thread if this list is being accesed by another thread. */PUBLIC IX_STATUS ixTimerCtrlScheduleRepeating(IxTimerCtrlTimerCallback func,                                 void *param,                                 IxTimerCtrlPurpose purpose,			        UINT32 interval,                                unsigned *timerId );/** * @ingroup IxTimerCtrl * * @fn ixTimerCtrlCancel (unsigned id) * * @brief Cancels a scheduled callback. * * @param id unsigned [in] - the id of the callback to be cancelled. * @return * @li IX_SUCCESS - The timer was successfully stopped. * @li IX_FAIL - The id parameter did not corrrespond to any running timer.. * @note This function is re-entrant. The function accesses a list of running timers * and may suspend the calling thread if this list is being accesed by another thread. */PUBLIC IX_STATUSixTimerCtrlCancel (unsigned id);/** * @ingroup IxTimerCtrl * * @fn ixTimerCtrlInit(void) * * @brief Initialise the Timer Control Component. * @return  * @li IX_SUCCESS - The timer control component initialized successfully. * @li IX_FAIL - The timer control component initialization failed, * or the component was already initialized. * @note This must be done before any other API function is called. * This function should be called once only and is not re-entrant. */PUBLIC IX_STATUSixTimerCtrlInit(void);/** * @ingroup IxTimerCtrl * * @fn ixTimerCtrlShow( void ) * * @brief Display the status of the Timer Control Component.  * @return void * @note Displays a list of running timers. * This function is not re-entrant. This function does not suspend the calling thread. */PUBLIC voidixTimerCtrlShow( void );#endif  /* IXTIMERCTRL_H */