264 lines
9.2 KiB
C
264 lines
9.2 KiB
C
/**
|
|
* @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 */
|
|
|