context.c

/*
 * context.c
 *
 * Copyright(c) 1998 - 2010 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   context.c 
 *  \brief  The Context-Engine is an OS independent module, which provides the
 *            infrustracture for switching from external contexts to the driver's context.
 *          This includes also the driver task itself (workqueue in Linux), which invokes the 
 *            driver specific handlers in the driver's context.
 *          The OS specific implementation under this module (e.g. task-switching or 
 *            protection-locking) is provided by the OS abstraction layer (osapi.c).
 * 
 *  \see    context.h, osapi.c
 */


#define __FILE_ID__  FILE_ID_125
#include "osApi.h"
#include "report.h"
#include "context.h"
#include "bmtrace_api.h"



#define MAX_CLIENTS     8   /* Maximum number of clients using context services */
#define MAX_NAME_SIZE   16  /* Maximum client's name string size */

#ifdef TI_DBG
typedef struct 
{
    TI_UINT32       uSize;                  /* Clients' name string size */
    char            sName [MAX_NAME_SIZE];  /* Clients' name string      */
} TClientName;	
#endif /* TI_DBG */

/* context module structure */
typedef struct 
{
	TI_HANDLE        hOs;
	TI_HANDLE        hReport; 

    TI_BOOL          bContextSwitchRequired;       /* Indicate if the driver should switch to its  */
                                                   /*   own context or not before handling events  */ 
    TI_HANDLE        hProtectionLock;              /* Handle of protection lock used by context clients */
    TI_UINT32        uNumClients;                  /* Number of registered clients      */
    TContextCbFunc   aClientCbFunc [MAX_CLIENTS];  /* Clients' callback functions       */
    TI_HANDLE        aClientCbHndl [MAX_CLIENTS];  /* Clients' callback handles         */
    TI_BOOL          aClientEnabled[MAX_CLIENTS];  /* Clients' enable/disable flags     */
    TI_BOOL          aClientPending[MAX_CLIENTS];  /* Clients' pending flags            */

#ifdef TI_DBG
    TClientName      aClientName   [MAX_CLIENTS];  /* Clients' name string              */
    TI_UINT32        aRequestCount [MAX_CLIENTS];  /* Clients' schedule requests counter*/
    TI_UINT32        aInvokeCount  [MAX_CLIENTS];  /* Clients' invocations counter      */
#endif

} TContext;	




/** 
 * \fn     context_Create 
 * \brief  Create the module 
 * 
 * Allocate and clear the module object.
 * 
 * \note    
 * \param  hOs      - Handle to Os Abstraction Layer
 * \return Handle of the allocated object 
 * \sa     context_Destroy
 */ 
TI_HANDLE context_Create (TI_HANDLE hOs)
{
	TI_HANDLE hContext;

	/* allocate module object */
	hContext = os_memoryAlloc (hOs, sizeof(TContext));
	
	if (!hContext)
	{
		WLAN_OS_REPORT (("context_Create():  Allocation failed!!\n"));
		return NULL;
	}
	
    os_memoryZero (hOs, hContext, (sizeof(TContext)));

	return (hContext);
}


/** 
 * \fn     context_Destroy
 * \brief  Destroy the module. 
 * 
 * Free the module memory.
 * 
 * \note   
 * \param  hContext - The module object
 * \return TI_OK on success or TI_NOK on failure 
 * \sa     context_Create
 */ 
TI_STATUS context_Destroy (TI_HANDLE hContext)
{
    TContext *pContext = (TContext *)hContext;

    /* Destroy the protection handle */
    os_protectDestroy (pContext->hOs, pContext->hProtectionLock);

    /* free module object */
	os_memoryFree (pContext->hOs, pContext, sizeof(TContext));
	
    return TI_OK;
}


/** 
 * \fn     context_Init 
 * \brief  Init required handles 
 * 
 * Init required handles.
 * 
 * \note    
 * \param  hContext  - The queue object
 * \param  hOs       - Handle to Os Abstraction Layer
 * \param  hReport   - Handle to report module
 * \return void        
 * \sa     
 */ 
void context_Init (TI_HANDLE hContext, TI_HANDLE hOs, TI_HANDLE hReport)
{
	TContext *pContext = (TContext *)hContext;

    pContext->hOs     = hOs;
    pContext->hReport = hReport;
	
    /* Create the module's protection lock and save its handle */
    pContext->hProtectionLock = os_protectCreate (pContext->hOs);
}


/** 
 * \fn     context_SetDefaults
 * \brief  Configure module with default settings
 * 
 * Set default setting which indicates if the driver should switch to 
 *     its own context or not before handling events
 * 
 * \note   
 * \param  hContext           - The module's object                                          
 * \param  pContextInitParams - The module's init parameters                              
 * \return TI_OK on success or TI_NOK on failure 
 * \sa     
 */ 
TI_STATUS context_SetDefaults (TI_HANDLE hContext, TContextInitParams *pContextInitParams)
{
	TContext *pContext = (TContext *)hContext;

    /* Set parameters */
    pContext->bContextSwitchRequired = pContextInitParams->bContextSwitchRequired;
	
    return TI_OK;
}


/** 
 * \fn     context_RegisterClient
 * \brief  Save client's parameters
 * 
 * This function is used by the Context clients in their init process, for registering 
 *   their information, 
 * This includes their callback function that should be invoked from the driver context
 *   when they are pending. 
 * 
 * \note   
 * \param  hContext - The module handle
 * \param  fCbFunc  - The client's callback function.
 * \param  hCbHndl  - The client's callback function handle.
 * \param  bEnable  - TRUE = Enabled.
 * \return TI_UINT32 - The index allocated for the client
 * \sa     
 */ 
TI_UINT32 context_RegisterClient (TI_HANDLE       hContext,
                                  TContextCbFunc  fCbFunc,
                                  TI_HANDLE       hCbHndl,
                                  TI_BOOL         bEnable,
                                  char           *sName,
                                  TI_UINT32       uNameSize)
{
	TContext *pContext = (TContext *)hContext;
    TI_UINT32 uClientId = pContext->uNumClients;

    /* If max number of clients is exceeded, report error and exit. */
    if (uClientId == MAX_CLIENTS) 
    {
        TRACE0(pContext->hReport, REPORT_SEVERITY_ERROR , "context_RegisterClient() MAX_CLIENTS limit exceeded!!\n");
        return 0;
    }

    /* Save the new client's parameters. */
    pContext->aClientCbFunc[uClientId]  = fCbFunc;
    pContext->aClientCbHndl[uClientId]  = hCbHndl;
    pContext->aClientEnabled[uClientId] = bEnable;
    pContext->aClientPending[uClientId] = TI_FALSE;

#ifdef TI_DBG
    if (uNameSize <= MAX_NAME_SIZE) 
    {
        os_memoryCopy(pContext->hOs, 
                      (void *)(pContext->aClientName[uClientId].sName),
                      (void *)sName, 
                      uNameSize);
        pContext->aClientName[uClientId].uSize = uNameSize;
    }
    else 
    {
        TRACE0(pContext->hReport, REPORT_SEVERITY_ERROR , "context_RegisterClient() MAX_NAME_SIZE limit exceeded!\n");
    }
#endif /* TI_DBG */

    /* Increment clients number and return new client ID. */
    pContext->uNumClients++;

    TRACE2(pContext->hReport, REPORT_SEVERITY_INIT , "context_RegisterClient(): Client=, ID=%d, enabled=%d\n", uClientId, bEnable);

    return uClientId;
}


/** 
 * \fn     context_RequestSchedule
 * \brief  Handle client's switch to driver's context.
 * 
 * This function is called by a client from external context event.
 * It sets the client's Pending flag and requests the driver's task scheduling.
 * Thus, the client's callback will be called afterwards from the driver context.
 * 
 * \note   
 * \param  hContext   - The module handle
 * \param  uClientId  - The client's index
 * \return void 
 * \sa     context_DriverTask
 */ 
void context_RequestSchedule (TI_HANDLE hContext, TI_UINT32 uClientId)
{
	TContext *pContext = (TContext *)hContext;

#ifdef TI_DBG
    pContext->aRequestCount[uClientId]++; 
    TRACE3(pContext->hReport, REPORT_SEVERITY_INFORMATION , "context_RequestSchedule(): Client=, ID=%d, enabled=%d, pending=%d\n", uClientId, pContext->aClientEnabled[uClientId], pContext->aClientPending[uClientId]);
#endif /* TI_DBG */

    /* Set client's Pending flag */
    pContext->aClientPending[uClientId] = TI_TRUE;

    /* 
     * If configured to switch context, request driver task scheduling.
     * Else (context switch not required) call the driver task directly. 
     */
    if (pContext->bContextSwitchRequired)
    {
        os_RequestSchedule (pContext->hOs);
    }
    else 
    {
        context_DriverTask (hContext);
    }
}


/** 
 * \fn     context_DriverTask
 * \brief  The driver task
 * 
 * This function is the driver's main task that always runs in the driver's 
 * single context, scheduled through the OS (the driver's workqueue in Linux). 
 * Only one instantiation of this task may run at a time!
 * 
 * \note   
 * \param  hContext   - The module handle
 * \return void 
 * \sa     context_RequestSchedule
 */ 
void context_DriverTask (TI_HANDLE hContext)
{
	TContext       *pContext = (TContext *)hContext;
    TContextCbFunc  fCbFunc;
    TI_HANDLE       hCbHndl;
    TI_UINT32       i;
    CL_TRACE_START_L1();

    TRACE0(pContext->hReport, REPORT_SEVERITY_INFORMATION , "context_DriverTask():\n");

    /* For all registered clients do: */
	for (i = 0; i < pContext->uNumClients; i++)
    {
        /* If client is pending and enabled */
        if (pContext->aClientPending[i]  &&  pContext->aClientEnabled[i])
        {
            #ifdef TI_DBG
                pContext->aInvokeCount[i]++; 
                TRACE1(pContext->hReport, REPORT_SEVERITY_INFORMATION , "Invoking - Client=, ID=%d\n", i);
            #endif /* TI_DBG */

            /* Clear client's pending flag */
            pContext->aClientPending[i] = TI_FALSE;

            /* Call client's callback function */
            fCbFunc = pContext->aClientCbFunc[i];
            hCbHndl = pContext->aClientCbHndl[i];
            fCbFunc(hCbHndl);
        }
    }

    CL_TRACE_END_L1("tiwlan_drv.ko", "CONTEXT", "TASK", "");
}


/** 
 * \fn     context_EnableClient / context_DisableClient
 * \brief  Enable a specific client activation
 * 
 * Called by the driver main when needed to enble/disable a specific event handling.
 * The Enable function also schedules the driver-task if the specified client is pending.
 * 
 * \note   
 * \param  hContext   - The module handle
 * \param  uClientId  - The client's index
 * \return void 
 * \sa     context_DriverTask
 */ 
void context_EnableClient (TI_HANDLE hContext, TI_UINT32 uClientId)
{
	TContext *pContext = (TContext *)hContext;

#ifdef TI_DBG
    if (pContext->aClientEnabled[uClientId])
    {
        TRACE0(pContext->hReport, REPORT_SEVERITY_ERROR , "context_EnableClient() Client  already enabled!!\n");
        return;
    }
    TRACE3(pContext->hReport, REPORT_SEVERITY_INFORMATION , "context_EnableClient(): Client=, ID=%d, enabled=%d, pending=%d\n", uClientId, pContext->aClientEnabled[uClientId], pContext->aClientPending[uClientId]);
#endif /* TI_DBG */

    /* Enable client */
    pContext->aClientEnabled[uClientId] = TI_TRUE;

    /* If client is pending, schedule driver task */
    if (pContext->aClientPending[uClientId])
    {
        /* 
         * If configured to switch context, request driver task scheduling.
         * Else (context switch not required) call the driver task directly. 
         */
        if (pContext->bContextSwitchRequired)
        {
            os_RequestSchedule (pContext->hOs);
        }
        else 
        {
            context_DriverTask (hContext);
        }
    }
}

void context_DisableClient (TI_HANDLE hContext, TI_UINT32 uClientId)
{
	TContext *pContext = (TContext *)hContext;

#ifdef TI_DBG
    if (!pContext->aClientEnabled[uClientId])
    {
        TRACE0(pContext->hReport, REPORT_SEVERITY_ERROR , "context_DisableClient() Client  already disabled!!\n");
        return;
    }
    TRACE3(pContext->hReport, REPORT_SEVERITY_INFORMATION , "context_DisableClient(): Client=, ID=%d, enabled=%d, pending=%d\n", uClientId, pContext->aClientEnabled[uClientId], pContext->aClientPending[uClientId]);
#endif /* TI_DBG */

    /* Disable client */
    pContext->aClientEnabled[uClientId] = TI_FALSE;
}


/** 
 * \fn     context_EnterCriticalSection / context_LeaveCriticalSection
 * \brief  Lock / Unlock context related critical sections
 * 
 * The context clients should use these functions for protecting their critical sections
 *   when handling context transition to driver context.
 * 
 * \note   
 * \param  hContext   - The module handle
 * \return void 
 * \sa     
 */ 
void context_EnterCriticalSection (TI_HANDLE hContext)
{
	TContext *pContext = (TContext *)hContext;

    TRACE0(pContext->hReport, REPORT_SEVERITY_INFORMATION , "context_EnterCriticalSection():\n");

    /* Start critical section protection */
    os_protectLock (pContext->hOs, pContext->hProtectionLock);
}

void context_LeaveCriticalSection (TI_HANDLE hContext)
{
	TContext *pContext = (TContext *)hContext;

    TRACE0(pContext->hReport, REPORT_SEVERITY_INFORMATION , "context_LeaveCriticalSection():\n");

    /* Stop critical section protection */
    os_protectUnlock (pContext->hOs, pContext->hProtectionLock);
}


/** 
 * \fn     context_Print
 * \brief  Print module information
 * 
 * Print the module's clients parameters.
 * 
 * \note   
 * \param  hContext - The queue object
 * \return void
 * \sa     
 */ 

#ifdef TI_DBG

void context_Print(TI_HANDLE hContext)
{
	TContext *pContext = (TContext *)hContext;
    TI_UINT32 i;

    WLAN_OS_REPORT(("context_Print():  %d Clients Registered:\n", pContext->uNumClients));
    WLAN_OS_REPORT(("=======================================\n"));
    WLAN_OS_REPORT(("bContextSwitchRequired = %d\n", pContext->bContextSwitchRequired));

	for (i = 0; i < pContext->uNumClients; i++)
	{
		WLAN_OS_REPORT(("Client %d - %s: CbFunc=0x%x, CbHndl=0x%x, Enabled=%d, Pending=%d, Requests=%d, Invoked=%d\n",
                        i,
                        pContext->aClientName[i].sName,
                        (TI_UINT32)pContext->aClientCbFunc[i],
                        (TI_UINT32)pContext->aClientCbHndl[i],
                        pContext->aClientEnabled[i],
                        pContext->aClientPending[i],
                        pContext->aRequestCount[i],
                        pContext->aInvokeCount[i] ));
	}
}

#endif /* TI_DBG */