| /** | |
| * @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_STATUS | |
| ixTimerCtrlCancel (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_STATUS | |
| ixTimerCtrlInit(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 void | |
| ixTimerCtrlShow( void ); | |
| #endif /* IXTIMERCTRL_H */ | |