/*
* scrApi.h
*
* 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 ScrApi.h
* \brief This file include public definitions for the SCR module, comprising its API.
* \
* \date 01-Dec-2004
*/
#ifndef __SCRAPI_H__
#define __SCRAPI_H__
#include "DrvMainModules.h"
/*
***********************************************************************
* Constant definitions.
***********************************************************************
*/
/*
***********************************************************************
* Enums.
***********************************************************************
*/
/** \enum EScrModeId
* \brief enumerates the different modes available in the system
*/
typedef enum
{
SCR_MID_NORMAL = 0, /**< Normal mode */
SCR_MID_SG, /**< Soft Gemini mode */
SCR_MID_NUM_OF_MODES
} EScrModeId;
/** \enum EScrGroupId
* \brief enumerates the different groups available in the system
*/
typedef enum
{
SCR_GID_IDLE = 0, /**< STA is idle */
SCR_GID_DRV_SCAN, /**< STA is disconnected, SME scans */
SCR_GID_APP_SCAN, /**< STA is disconnected, application scans */
SCR_GID_CONNECT, /**< STA is trying to conenct */
SCR_GID_CONNECTED, /**< STA is connected */
SCR_GID_ROAMING, /**< STA is performing roaming to another AP */
SCR_GID_NUM_OF_GROUPS
} EScrGroupId;
/** \enum EScrResourceId
* \brief enumerates the different resources controlled by the SCR
*/
typedef enum
{
SCR_RESOURCE_SERVING_CHANNEL = 0,
SCR_RESOURCE_PERIODIC_SCAN,
SCR_RESOURCE_NUM_OF_RESOURCES
} EScrResourceId;
/** \enum EScrClientId
* \brief enumerates the different clients available in the system
*/
typedef enum
{
SCR_CID_APP_SCAN = 0, /* lowest priority */
SCR_CID_DRIVER_FG_SCAN,
SCR_CID_CONT_SCAN,
SCR_CID_XCC_MEASURE,
SCR_CID_BASIC_MEASURE,
SCR_CID_CONNECT,
SCR_CID_IMMED_SCAN,
SCR_CID_SWITCH_CHANNEL, /* highest priority */
SCR_CID_NUM_OF_CLIENTS,
SCR_CID_NO_CLIENT
} EScrClientId;
/** \enum EScrClientRequestStatus
* \brief enumerates the status reports the client may receive
*/
typedef enum
{
SCR_CRS_RUN = 0, /**< the client can use the channel */
SCR_CRS_PEND, /**< the channel is in use, The client may wait for it. */
SCR_CRS_ABORT, /**< client should abort it's use of the channel */
SCR_CRS_FW_RESET /**< Notification of recovery (client should elect what to do) */
} EScrClientRequestStatus;
/** \enum EScePendReason
* \brief enumerates the different reasons which can cause a client request to return with pend status.
*/
typedef enum
{
SCR_PR_OTHER_CLIENT_ABORTING = 0, /**<
* The requesting client is waiting for a client with lower priority
* to abort operation
*/
SCR_PR_OTHER_CLIENT_RUNNING, /**<
* The requesting client is waiting for a client that cannot be aborted
* to finish using the channel.
*/
SCR_PR_DIFFERENT_GROUP_RUNNING, /**< The current SCR group is different than the client's group */
SCR_PR_NONE /**< The client is not pending */
} EScePendReason;
/*
***********************************************************************
* Typedefs.
***********************************************************************
*/
/** \typedef scr_abortReason_e
* \brief Defines the function prototype a client should register as callback.
*/
typedef void (*TScrCB)( TI_HANDLE hClient,
EScrClientRequestStatus requestStatus,
EScrResourceId eResource,
EScePendReason pendReason );
/*
***********************************************************************
* Structure definitions.
***********************************************************************
*/
/*
***********************************************************************
* External data definitions.
***********************************************************************
*/
/*
***********************************************************************
* External functions definitions
***********************************************************************
*/
/**
* \\n
* \date 01-Dec-2004\n
* \brief Creates the SCR object
*
* Function Scope \e Public.\n
* \param hOS - handle to the OS object.\n
* \return a handle to the SCR object.\n
*/
TI_HANDLE scr_create( TI_HANDLE hOS );
/**
* \\n
* \date 01-Dec-2004\n
* \brief Finalizes the SCR object (freeing memory)
*
* Function Scope \e Public.\n
* \param hScr - handle to the SCR object.\n
*/
void scr_release( TI_HANDLE hScr );
/**
* \\n
* \date 01-Dec-2004\n
* \brief Initializes the SCR object
*
* \param pStadHandles - The driver modules handles
* \return void
*/
void scr_init (TStadHandlesList *pStadHandles);
/**
* \\n
* \date 01-Dec-2004\n
* \brief Registers the callback function to be used per client.
*
* Function Scope \e Public.\n
* \param hScr - handle to the SCR object.\n
* \param client - the client ID.\n
* \param callbackFunc - the address of the callback function to use.\n
* \param callbackObj - the handle of the object to pass to the callback function (the client object).\n
*/
void scr_registerClientCB( TI_HANDLE hScr,
EScrClientId client,
TScrCB callbackFunc,
TI_HANDLE callbackObj );
/**
* \\n
* \date 01-Dec-2004\n
* \brief Notifies the running process upon a firmware reset.
*
* Function Scope \e Public.\n
* \param hScr - handle to the SCR object.\n
*/
void scr_notifyFWReset( TI_HANDLE hScr );
/**
* \\n
* \date 27-April-2005\n
* \brief Changes the current SCR group.\n
*
* Function Scope \e Public.\n
* \param hScr - handle to the SCR object.\n
* \param newGroup - the new group to use.\n
*/
void scr_setGroup( TI_HANDLE hScr, EScrGroupId newGroup );
/**
* \\n
* \date 23-1l-2005\n
* \brief Changes the current SCR mode. This function is called from Soft Gemini module only \n
* when changing mode - clients that are not valid in the new group/mode are aborted \n
*
* Function Scope \e Public.\n
* \param hScr - handle to the SCR object.\n
* \param newMode - the new mode to use.\n
*/
void scr_setMode( TI_HANDLE hScr, EScrModeId newMode );
/**
* \\n
* \date 01-Dec-2004\n
* \brief Request the channel use by a client
*
* Function Scope \e Public.\n
* \param hScr - handle to the SCR object.\n
* \param client - the client ID requesting the channel.\n
* \param eResource - the requested resource.\n
* \param pPendReason - the reason for a pend reply.\n
* \return The request status.\n
* \retval SCR_CRS_REJECT the channel cannot be allocated to this client.
* \retval SCR_CRS_PEND the channel is currently busy, and this client had been placed on the waiting list.
* \retval SCR_CRS_RUN the channel is allocated to this client.
*/
EScrClientRequestStatus scr_clientRequest( TI_HANDLE hScr, EScrClientId client,
EScrResourceId eResource,
EScePendReason* pPendReason );
/**
* \\n
* \date 01-Dec-2004\n
* \brief Notifies the SCR that the client doe not require the channel any longer
*
* This function can be called both by clients that are in possession of the channel, and by
* clients that are pending to use the channel.\n
* Function Scope \e Public.\n
* \param hScr - handle to the SCR object.\n
* \param client - the client releasing the channel.\n
* \param eResource - the resource being released.\n
* \return TI_OK if successful, TI_NOK otherwise.\n
*/
void scr_clientComplete( TI_HANDLE hScr, EScrClientId client, EScrResourceId eResource );
#endif /* __SCRAPI_H__ */