/*

 * timer.c

 *

 * Copyright(c) 1998 - 2010 Texas Instruments. All rights reserved.      

 * All rights reserved.      

 * 

 * This program and the accompanying materials are made available under the 

 * terms of the Eclipse Public License v1.0 or BSD License which accompanies

 * this distribution. The Eclipse Public License is available at

 * http://www.eclipse.org/legal/epl-v10.html and the BSD License is as below.                                   

 *                                                                       

 * 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

 */

#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),MemoryNormal);

	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;

    while (que_Dequeue (pTimerModule->hInitQueue) != NULL) {}

}

void tmr_ClearOperQueue (TI_HANDLE hTimerModule)

{

    TTimerModule *pTimerModule = (TTimerModule *)hTimerModule;

    while (que_Dequeue (pTimerModule->hOperQueue) != 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;

    if (bOperState == pTimerModule->bOperState) 

    {

        TRACE1(pTimerModule->hReport, REPORT_SEVERITY_ERROR, "tmr_UpdateDriverState(): New bOperState (%d) is as current!\n", bOperState);

        return;

    }

    /* Enter critical section */

    CONTEXT_ENTER_CRITICAL_SECTION (pTimerModule->hContext);

    /* 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++;

        /* Empty the init queue (obsolete). */

        while (que_Dequeue (pTimerModule->hInitQueue) != NULL) {}

    }

    /* Leave critical section */

    CONTEXT_LEAVE_CRITICAL_SECTION (pTimerModule->hContext);

    /* 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),MemoryNormal);

	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)

	{

        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 = (TTimerModule *)pTimerInfo->hTimerModule; /* The timer module handle */

    /* Free the OS-API timer */

    os_timerDestroy (pTimerModule->hOs, pTimerInfo->hOsTimerObj);

    /* Free the timer object */

    os_memoryFree (pTimerModule->hOs, hTimerInfo, sizeof(TTimerInfo));

    pTimerModule->uTimersCount--;  /* update created timers number */

    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_ENTER_CRITICAL_SECTION (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_LEAVE_CRITICAL_SECTION (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_ENTER_CRITICAL_SECTION (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 */