diff options
Diffstat (limited to 'wilink_6_1/utils/timer.c')
| -rw-r--r-- | wilink_6_1/utils/timer.c | 616 |
1 files changed, 616 insertions, 0 deletions
diff --git a/wilink_6_1/utils/timer.c b/wilink_6_1/utils/timer.c new file mode 100644 index 0000000..0fbd726 --- /dev/null +++ b/wilink_6_1/utils/timer.c @@ -0,0 +1,616 @@ +/* + * timer.c + * + * Copyright(c) 1998 - 2009 Texas Instruments. All rights reserved. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * 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. + * * Neither the name Texas Instruments nor the names of its + * contributors may be used to endorse or promote products derived + * from this software without specific prior written permission. + * + * 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. + */ + + +/** \file timer.c + * \brief The timers services OS-Independent layer over the OS-API timer services which are OS-Dependent. + * + * \see timer.h, osapi.c + */ + +#include <linux/kernel.h> +#define __FILE_ID__ FILE_ID_0 +#include "osApi.h" +#include "report.h" +#include "queue.h" +#include "context.h" +#include "timer.h" + + +#define EXPIRY_QUE_SIZE 64 /* support case where all timers expire during recovery or error */ + +/* The timer module structure (common to all timers) */ +typedef struct +{ + TI_HANDLE hOs; + TI_HANDLE hReport; + TI_HANDLE hContext; + TI_UINT32 uContextId; /* The ID allocated to this module on registration to context module */ + TI_HANDLE hInitQueue; /* Handle of the Init-Queue */ + TI_HANDLE hOperQueue; /* Handle of the Operational-Queue */ + TI_BOOL bOperState; /* TRUE when the driver is in operational state (not init or recovery) */ + TI_UINT32 uTwdInitCount; /* Increments on each TWD init (i.e. recovery) */ + TI_UINT32 uTimersCount; /* Number of created timers */ +} TTimerModule; + +/* Per timer structure */ +typedef struct +{ + TI_HANDLE hTimerModule; /* The timer module handle (see TTimerModule, needed on expiry) */ + TI_HANDLE hOsTimerObj; /* The OS-API timer object handle */ + TQueNodeHdr tQueNodeHdr; /* The header used for queueing the timer */ + TTimerCbFunc fExpiryCbFunc; /* The CB-function provided by the timer user for expiration */ + TI_HANDLE hExpiryCbHndl; /* The CB-function handle */ + TI_UINT32 uIntervalMsec; /* The timer duration in Msec */ + TI_BOOL bPeriodic; /* If TRUE, restarted after each expiry */ + TI_BOOL bOperStateWhenStarted; /* The bOperState value when the timer was started */ + TI_UINT32 uTwdInitCountWhenStarted; /* The uTwdInitCount value when the timer was started */ +} TTimerInfo; + + + + +/** + * \fn tmr_Create + * \brief Create the timer module + * + * Allocate and clear the timer module object. + * + * \note This is NOT a specific timer creation! (see tmr_CreateTimer) + * \param hOs - Handle to Os Abstraction Layer + * \return Handle of the allocated object + * \sa tmr_Destroy + */ +TI_HANDLE tmr_Create (TI_HANDLE hOs) +{ + TI_HANDLE hTimerModule; + + /* allocate module object */ + hTimerModule = os_memoryAlloc (hOs, sizeof(TTimerModule)); + + if (!hTimerModule) + { + WLAN_OS_REPORT (("tmr_Create(): Allocation failed!!\n")); + return NULL; + } + + os_memoryZero (hOs, hTimerModule, (sizeof(TTimerModule))); + + return (hTimerModule); +} + + +/** + * \fn tmr_Destroy + * \brief Destroy the module. + * + * Free the module's queues and object. + * + * \note This is NOT a specific timer destruction! (see tmr_DestroyTimer) + * \param hTimerModule - The module object + * \return TI_OK on success or TI_NOK on failure + * \sa tmr_Create + */ +TI_STATUS tmr_Destroy (TI_HANDLE hTimerModule) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; + + /* Alert if there are still timers that were not destroyed */ + if (pTimerModule->uTimersCount) + { + WLAN_OS_REPORT (("tmr_Destroy(): ERROR - Destroying Timer module but not all timers were destroyed!!\n")); + } + + /* Clear queues */ + tmr_ClearInitQueue (hTimerModule); + tmr_ClearOperQueue (hTimerModule); + + /* Destroy the module's queues */ + que_Destroy (pTimerModule->hInitQueue); + que_Destroy (pTimerModule->hOperQueue); + + /* free module object */ + os_memoryFree (pTimerModule->hOs, pTimerModule, sizeof(TTimerModule)); + + return TI_OK; +} +/** + * \fn tmr_Free + * \brief Free the memory. + * + * Free the module's queues and object. + * + * \param hTimerModule - The module object + * \return TI_OK on success or TI_NOK on failure + * \sa tmr_Create + */ +TI_STATUS tmr_Free(TI_HANDLE hTimerModule) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; + + /* free module object */ + os_memoryFree (pTimerModule->hOs, pTimerModule, sizeof(TTimerModule)); + + return TI_OK; +} + + +/** + * \fn tmr_ClearInitQueue & tmr_ClearOperQueue + * \brief Clear Init/Operationsl queue + * + * Dequeue all queued timers. + * + * \note + * \param hTimerModule - The object + * \return void + * \sa + */ +void tmr_ClearInitQueue (TI_HANDLE hTimerModule) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; + TTimerInfo *pTimerInfo; /* The timer handle */ + + do { + context_EnterCriticalSection (pTimerModule->hContext); + pTimerInfo = que_Dequeue (pTimerModule->hInitQueue); + context_LeaveCriticalSection (pTimerModule->hContext); + } while (pTimerInfo != NULL); +} + +void tmr_ClearOperQueue (TI_HANDLE hTimerModule) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; + TTimerInfo *pTimerInfo; /* The timer handle */ + + do { + context_EnterCriticalSection (pTimerModule->hContext); + pTimerInfo = que_Dequeue (pTimerModule->hOperQueue); + context_LeaveCriticalSection (pTimerModule->hContext); + } while (pTimerInfo != NULL); +} + + +/** + * \fn tmr_Init + * \brief Init required handles + * + * Init required handles and module variables, create the init-queue and + * operational-queue, and register as the context-engine client. + * + * \note + * \param hTimerModule - The queue object + * \param hOs - Handle to Os Abstraction Layer + * \param hReport - Handle to report module + * \param hContext - Handle to context module + * \return void + * \sa + */ +void tmr_Init (TI_HANDLE hTimerModule, TI_HANDLE hOs, TI_HANDLE hReport, TI_HANDLE hContext) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; + TI_UINT32 uNodeHeaderOffset; + + pTimerModule->hOs = hOs; + pTimerModule->hReport = hReport; + pTimerModule->hContext = hContext; + + pTimerModule->bOperState = TI_FALSE; + pTimerModule->uTimersCount = 0; + pTimerModule->uTwdInitCount = 0; + + /* The offset of the queue-node-header from timer structure entry is needed by the queue */ + uNodeHeaderOffset = TI_FIELD_OFFSET(TTimerInfo, tQueNodeHdr); + + /* Create and initialize the Init and Operational queues (for timers expiry events) */ + pTimerModule->hInitQueue = que_Create (pTimerModule->hOs, + pTimerModule->hReport, + EXPIRY_QUE_SIZE, + uNodeHeaderOffset); + pTimerModule->hOperQueue = que_Create (pTimerModule->hOs, + pTimerModule->hReport, + EXPIRY_QUE_SIZE, + uNodeHeaderOffset); + + /* Register to the context engine and get the client ID */ + pTimerModule->uContextId = context_RegisterClient (pTimerModule->hContext, + tmr_HandleExpiry, + hTimerModule, + TI_TRUE, + "TIMER", + sizeof("TIMER")); +} + + +/** + * \fn tmr_UpdateDriverState + * \brief Update driver state + * + * Under critical section, update driver state (operational or not), + * and if opertional, clear init queue. + * Leave critical section and if operational state, request schedule for handling + * timer events in driver context (if any). + * + * \note + * \param hTimerModule - The timer module object + * \param bOperState - TRUE if driver state is now operational, FALSE if not. + * \return void + * \sa + */ +void tmr_UpdateDriverState (TI_HANDLE hTimerModule, TI_BOOL bOperState) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; + TTimerInfo *pTimerInfo; /* The timer handle */ + + /* Enter critical section */ + context_EnterCriticalSection (pTimerModule->hContext); + + if (bOperState == pTimerModule->bOperState) + { + context_LeaveCriticalSection (pTimerModule->hContext); + TRACE1(pTimerModule->hReport, REPORT_SEVERITY_ERROR, "tmr_UpdateDriverState(): New bOperState (%d) is as current!\n", bOperState); + return; + } + + /* Save new state (TRUE means operational). */ + pTimerModule->bOperState = bOperState; + + /* If new state is operational */ + if (bOperState) + { + /* Increment the TWD initializations counter (for detecting recovery events). */ + pTimerModule->uTwdInitCount++; + } + + /* Leave critical section */ + context_LeaveCriticalSection (pTimerModule->hContext); + + /* If new state is operational */ + if (bOperState) + { + /* Empty the init queue (obsolete). */ + do { + context_EnterCriticalSection (pTimerModule->hContext); + pTimerInfo = que_Dequeue (pTimerModule->hInitQueue); + context_LeaveCriticalSection (pTimerModule->hContext); + } while (pTimerInfo != NULL); + } + + /* If new state is operational, request switch to driver context for handling timer events */ + if (bOperState) + { + context_RequestSchedule (pTimerModule->hContext, pTimerModule->uContextId); + } +} + + + +/** + * \fn tmr_CreateTimer + * \brief Create a new timer + * + * Create a new timer object, icluding creating a timer in the OS-API. + * + * \note This timer creation may be used only after tmr_Create() and tmr_Init() were executed!! + * \param hTimerModule - The module handle + * \return TI_HANDLE - The created timer handle + * \sa tmr_DestroyTimer + */ +TI_HANDLE tmr_CreateTimer (TI_HANDLE hTimerModule) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; /* The timer module handle */ + TTimerInfo *pTimerInfo; /* The created timer handle */ + + /* Allocate timer object */ + pTimerInfo = os_memoryAlloc (pTimerModule->hOs, sizeof(TTimerInfo)); + if (!pTimerInfo) + { + WLAN_OS_REPORT (("tmr_CreateTimer(): Timer allocation failed!!\n")); + return NULL; + } + os_memoryZero (pTimerModule->hOs, pTimerInfo, (sizeof(TTimerInfo))); + + /* Allocate OS-API timer, providing the common expiry callback with the current timer handle */ + pTimerInfo->hOsTimerObj = os_timerCreate(pTimerModule->hOs, tmr_GetExpiry, (TI_HANDLE)pTimerInfo); + if (!pTimerInfo->hOsTimerObj) + { + TRACE0(pTimerModule->hReport, REPORT_SEVERITY_CONSOLE ,"tmr_CreateTimer(): OS-API Timer allocation failed!!\n"); + os_memoryFree (pTimerModule->hOs, pTimerInfo, sizeof(TTimerInfo)); + WLAN_OS_REPORT (("tmr_CreateTimer(): OS-API Timer allocation failed!!\n")); + return NULL; + } + + /* Save the timer module handle in the created timer object (needed for the expiry callback) */ + pTimerInfo->hTimerModule = hTimerModule; + pTimerModule->uTimersCount++; /* count created timers */ + + /* Return the created timer handle */ + return (TI_HANDLE)pTimerInfo; +} + + +/** + * \fn tmr_DestroyTimer + * \brief Destroy the specified timer + * + * Destroy the specified timer object, icluding the timer in the OS-API. + * + * \note This timer destruction function should be used before tmr_Destroy() is executed!! + * \param hTimerInfo - The timer handle + * \return TI_OK on success or TI_NOK on failure + * \sa tmr_CreateTimer + */ +TI_STATUS tmr_DestroyTimer (TI_HANDLE hTimerInfo) +{ + TTimerInfo *pTimerInfo = (TTimerInfo *)hTimerInfo; /* The timer handle */ + TTimerModule *pTimerModule; /* The timer module handle */ + + if (!pTimerInfo) + return TI_NOK; + pTimerModule = (TTimerModule *)pTimerInfo->hTimerModule; + /* Free the OS-API timer */ + if (pTimerInfo->hOsTimerObj) { + os_timerDestroy (pTimerModule->hOs, pTimerInfo->hOsTimerObj); + pTimerModule->uTimersCount--; /* update created timers number */ + } + /* Free the timer object */ + os_memoryFree (pTimerModule->hOs, hTimerInfo, sizeof(TTimerInfo)); + return TI_OK; +} + + +/** + * \fn tmr_StartTimer + * \brief Start a timer + * + * Start the specified timer running. + * + * \note Periodic-Timer may be used by applications that serve the timer expiry + * in a single context. + * If an application can't finish serving the timer expiry in a single context, + * e.g. periodic scan, then it isn't recommended to use the periodic timer service. + * If such an application uses the periodic timer then it should protect itself from cases + * where the timer expires again before the previous timer expiry processing is finished!! + * \param hTimerInfo - The specific timer handle + * \param fExpiryCbFunc - The timer's expiry callback function. + * \param hExpiryCbHndl - The client's expiry callback function handle. + * \param uIntervalMsec - The timer's duration in Msec. + * \param bPeriodic - If TRUE, the timer is restarted after expiry. + * \return void + * \sa tmr_StopTimer, tmr_GetExpiry + */ +void tmr_StartTimer (TI_HANDLE hTimerInfo, + TTimerCbFunc fExpiryCbFunc, + TI_HANDLE hExpiryCbHndl, + TI_UINT32 uIntervalMsec, + TI_BOOL bPeriodic) +{ + TTimerInfo *pTimerInfo = (TTimerInfo *)hTimerInfo; /* The timer handle */ + TTimerModule *pTimerModule = (TTimerModule *)pTimerInfo->hTimerModule; /* The timer module handle */ + + /* Save the timer parameters. */ + pTimerInfo->fExpiryCbFunc = fExpiryCbFunc; + pTimerInfo->hExpiryCbHndl = hExpiryCbHndl; + pTimerInfo->uIntervalMsec = uIntervalMsec; + pTimerInfo->bPeriodic = bPeriodic; + pTimerInfo->bOperStateWhenStarted = pTimerModule->bOperState; + pTimerInfo->uTwdInitCountWhenStarted = pTimerModule->uTwdInitCount; + + /* Start OS-API timer running */ + os_timerStart(pTimerModule->hOs, pTimerInfo->hOsTimerObj, uIntervalMsec); +} + + +/** + * \fn tmr_StopTimer + * \brief Stop a running timer + * + * Stop the specified timer. + * + * \note When using this function, it must be considered that timer expiry may happen + * right before the timer is stopped, so it can't be assumed that this completely + * prevents the timer expiry event! + * \param hTimerInfo - The specific timer handle + * \return void + * \sa tmr_StartTimer + */ +void tmr_StopTimer (TI_HANDLE hTimerInfo) +{ + TTimerInfo *pTimerInfo = (TTimerInfo *)hTimerInfo; /* The timer handle */ + TTimerModule *pTimerModule = (TTimerModule *)pTimerInfo->hTimerModule; /* The timer module handle */ + + /* Stop OS-API timer running */ + os_timerStop(pTimerModule->hOs, pTimerInfo->hOsTimerObj); + + /* Clear periodic flag to prevent timer restart if we are in tmr_HandleExpiry context. */ + pTimerInfo->bPeriodic = TI_FALSE; +} + + +/** + * \fn tmr_GetExpiry + * \brief Called by OS-API upon any timer expiry + * + * This is the common callback function called upon expiartion of any timer. + * It is called by the OS-API in timer expiry context and handles the transition + * to the driver's context for handling the expiry event. + * + * \note + * \param hTimerInfo - The specific timer handle + * \return void + * \sa tmr_HandleExpiry + */ +void tmr_GetExpiry (TI_HANDLE hTimerInfo) +{ + TTimerInfo *pTimerInfo = (TTimerInfo *)hTimerInfo; /* The timer handle */ + TTimerModule *pTimerModule = (TTimerModule *)pTimerInfo->hTimerModule; /* The timer module handle */ + + /* Enter critical section */ + context_EnterCriticalSection (pTimerModule->hContext); + + /* + * If the expired timer was started when the driver's state was Operational, + * insert it to the Operational-queue + */ + if (pTimerInfo->bOperStateWhenStarted) + { + que_Enqueue (pTimerModule->hOperQueue, hTimerInfo); + } + + /* + * Else (started when driver's state was NOT-Operational), if now the state is still + * NOT Operational insert it to the Init-queue. + * (If state changed from non-operational to operational the event is ignored) + */ + else if (!pTimerModule->bOperState) + { + que_Enqueue (pTimerModule->hInitQueue, hTimerInfo); + } + + /* Leave critical section */ + context_LeaveCriticalSection (pTimerModule->hContext); + + /* Request switch to driver context for handling timer events */ + context_RequestSchedule (pTimerModule->hContext, pTimerModule->uContextId); +} + + +/** + * \fn tmr_HandleExpiry + * \brief Handles queued expiry events in driver context + * + * This is the Timer module's callback that is registered to the ContextEngine module to be invoked + * from the driver task (after requested by tmr_GetExpiry through context_RequestSchedule ()). + * It dequeues all expiry events from the queue that correlates to the current driver state, + * and calls their users callbacks. + * + * \note + * \param hTimerModule - The module object + * \return void + * \sa tmr_GetExpiry + */ +void tmr_HandleExpiry (TI_HANDLE hTimerModule) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; /* The timer module handle */ + TTimerInfo *pTimerInfo; /* The timer handle */ + TI_BOOL bTwdInitOccured; /* Indicates if TWD init occured since timer start */ + + while (1) + { + /* Enter critical section */ + context_EnterCriticalSection (pTimerModule->hContext); + + /* If current driver state is Operational, dequeue timer object from Operational-queue */ + if (pTimerModule->bOperState) + { + pTimerInfo = (TTimerInfo *) que_Dequeue (pTimerModule->hOperQueue); + } + + /* Else (driver state is NOT-Operational), dequeue timer object from Init-queue */ + else + { + pTimerInfo = (TTimerInfo *) que_Dequeue (pTimerModule->hInitQueue); + } + + /* Leave critical section */ + context_LeaveCriticalSection (pTimerModule->hContext); + + /* If no more objects in queue, exit */ + if (!pTimerInfo) + { + return; /** EXIT Point **/ + } + + /* If current TWD-Init-Count is different than when the timer was started, Init occured. */ + bTwdInitOccured = (pTimerModule->uTwdInitCount != pTimerInfo->uTwdInitCountWhenStarted); + + /* Call specific timer callback function */ + pTimerInfo->fExpiryCbFunc (pTimerInfo->hExpiryCbHndl, bTwdInitOccured); + + /* If the expired timer is periodic, start it again. */ + if (pTimerInfo->bPeriodic) + { + tmr_StartTimer ((TI_HANDLE)pTimerInfo, + pTimerInfo->fExpiryCbFunc, + pTimerInfo->hExpiryCbHndl, + pTimerInfo->uIntervalMsec, + pTimerInfo->bPeriodic); + } + } +} + + +/** + * \fn tmr_PrintModule / tmr_PrintTimer + * \brief Print module / timer information + * + * Print the module's information / a specific timer information. + * + * \note + * \param The module / timer handle + * \return void + * \sa + */ + +#ifdef TI_DBG + +void tmr_PrintModule (TI_HANDLE hTimerModule) +{ + TTimerModule *pTimerModule = (TTimerModule *)hTimerModule; + + /* Print module parameters */ + WLAN_OS_REPORT(("tmr_PrintModule(): uContextId=%d, bOperState=%d, uTwdInitCount=%d, uTimersCount=%d\n", + pTimerModule->uContextId, pTimerModule->bOperState, + pTimerModule->uTwdInitCount, pTimerModule->uTimersCount)); + + /* Print Init Queue Info */ + WLAN_OS_REPORT(("tmr_PrintModule(): Init-Queue:\n")); + que_Print(pTimerModule->hInitQueue); + + /* Print Operational Queue Info */ + WLAN_OS_REPORT(("tmr_PrintModule(): Operational-Queue:\n")); + que_Print(pTimerModule->hOperQueue); +} + +void tmr_PrintTimer (TI_HANDLE hTimerInfo) +{ +#ifdef REPORT_LOG + TTimerInfo *pTimerInfo = (TTimerInfo *)hTimerInfo; /* The timer handle */ + + WLAN_OS_REPORT(("tmr_PrintTimer(): uIntervalMs=%d, bPeriodic=%d, bOperStateWhenStarted=%d, uTwdInitCountWhenStarted=%d, hOsTimerObj=0x%x, fExpiryCbFunc=0x%x\n", + pTimerInfo->uIntervalMsec, pTimerInfo->bPeriodic, pTimerInfo->bOperStateWhenStarted, + pTimerInfo->uTwdInitCountWhenStarted, pTimerInfo->hOsTimerObj, pTimerInfo->fExpiryCbFunc)); +#endif +} + +#endif /* TI_DBG */ |