/*
* MeasurementSrv.h
*
* 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 MeasurementSrv.h
* \brief This file include private definitions for the Measurement SRV module.
* \author Ronen Kalish
* \date 08-November-2005
*/
#ifndef __MEASUREMENT_SRV_H__
#define __MEASUREMENT_SRV_H__
#include "TWDriverInternal.h"
#include "MacServices_api.h"
#include "fsm.h"
#include "MeasurementSrvSM.h"
/*
***********************************************************************
* Constant definitions.
***********************************************************************
*/
/* Time in milliseconds to receive a command complete for measure start / stop from the FW */
#define MSR_FW_GUARD_TIME 100
#define DEF_SAMPLE_INTERVAL (100) /* expressed in microsec */
#define NOISE_HISTOGRAM_THRESHOLD 100
/* Get param callback flags */
#define MSR_SRV_WAITING_CHANNEL_LOAD_RESULTS 0x01 /* channel load results are still pending */
#define MSR_SRV_WAITING_NOISE_HIST_RESULTS 0x02 /* noise histogram results are still pending */
/*
***********************************************************************
* Enums.
***********************************************************************
*/
/*
***********************************************************************
* Typedefs.
***********************************************************************
*/
/*
***********************************************************************
* Structure definitions.
***********************************************************************
*/
/** \struct measurementSRV_t
* \brief This structure contains the measurement SRV object data
*/
typedef struct
{
TMediumOccupancy mediumOccupancyResults; /**< channel load results buffer */
TNoiseHistogramResults noiseHistogramResults; /**< noise histogram results buffer */
/* module handles */
TI_HANDLE hOS; /**< OS object handle */
TI_HANDLE hReport; /**< report object handle */
TI_HANDLE hPowerSaveSRV; /**< power save SRV object handle */
TI_HANDLE hCmdBld; /**< Command Builder object handle */
TI_HANDLE hEventMbox; /**< Event Mbox handle */
TI_HANDLE hTimer ; /**< Timer Module handle */
/* CB functions and objects */
TMeasurementSrvCompleteCb measurmentCompleteCBFunc;
/**<
* upper layer (measurement manager) measurement complete
* callback function
*/
TI_HANDLE measurementCompleteCBObj; /**<
* upper layer (measurement manager) measurement complete
* callback object
*/
TCmdResponseCb commandResponseCBFunc; /**<
* upper layer command response CB, used for both start
* and stop. Passed down to the HAL and called when
* the measurement command has been received by the FW
*/
TI_HANDLE commandResponseCBObj; /**<
* object parameter passed to the commandResposeFunc by
* the HAL when it is called
*/
TFailureEventCb failureEventFunc; /**<
* upper layer Failure Event CB.
* called when the scan command has been Timer Expiry
*/
TI_HANDLE failureEventObj; /**<
* object parameter passed to the failureEventFunc
* when it is called
*/
/* Timers */
TI_HANDLE hRequestTimer[ MAX_NUM_OF_MSR_TYPES_IN_PARALLEL ];
/**< Timers for different measurement types */
TI_BOOL bRequestTimerRunning[ MAX_NUM_OF_MSR_TYPES_IN_PARALLEL ];
/**< Indicates whether each request timer is running */
TI_HANDLE hStartStopTimer; /**< Timer for start / stop commands guard */
TI_BOOL bStartStopTimerRunning; /**<
* Indicates whether the start / stop command guard
* timer is running
*/
/* Misc stuff */
TI_BOOL bInRequest; /**<
* Indicates whether the SM is run within
* the measurement request context (if so, to avoid
* re-entrance, the complete function shouldn't
* be called on failure, but rather an invalid
* status should be returned)
*/
TI_STATUS returnStatus; /**<
* Holds the return code to the upper layer
* Used to save errors during SM operation.
*/
TI_BOOL bSendNullDataWhenExitPs; /**< whether to send NULL data frame when exiting
* driver mode
*/
/* state machine */
fsm_stateMachine_t* SM; /**<
* state machines for different
* scan types
*/
measurements_SRVSMStates_e SMState; /**< state machine current states */
/* measurement request */
TMeasurementRequest msrRequest; /**< measurement request parameters */
TMeasurementReply msrReply; /**< measurement reply values */
TI_UINT32 requestRecptionTimeStampMs; /**< The time in which the request was received. */
TI_UINT32 timeToRequestExpiryMs; /**<
* The duration (in ms) from request receiption
* until it should actually start. Request is
* discarded if a longer period is required
*/
TI_UINT8 pendingParamCBs; /**<
* a bitmap indicating which get_param CBs are
* currently pending (noise histogram and/or
* channel load).
*/
} measurementSRV_t;
/*
***********************************************************************
* External data definitions.
***********************************************************************
*/
/*
***********************************************************************
* External functions definitions
***********************************************************************
*/
/**
* \author Ronen Kalish\n
* \date 08-November-2005\n
* \brief Creates the measurement SRV object
*
* Function Scope \e Public.\n
* \param hOS - handle to the OS object.\n
* \return a handle to the measurement SRV object, NULL if an error occurred.\n
*/
TI_HANDLE MacServices_measurementSRV_create( TI_HANDLE hOS );
/**
* \author Ronen Kalish\n
* \date 08-November-2005\n
* \brief Initializes the measurement SRV object
*
* Function Scope \e Public.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
* \param hReport - handle to the report object.\n
* \param hCmdBld - handle to the Command Builder object.\n
* \param hEventMbox - handle to the Event Mbox object.\n
* \param hPowerSaveSRV - handle to the power save SRV object.\n
* \param hTimer - handle to the Timer module object.\n
*/
TI_STATUS MacServices_measurementSRV_init (TI_HANDLE hMeasurementSRV,
TI_HANDLE hReport,
TI_HANDLE hCmdBld,
TI_HANDLE hEventMbox,
TI_HANDLE hPowerSaveSRV,
TI_HANDLE hTimer);
/**
* \author Ronen Kalish\n
* \date 08-November-2005\n
* \brief Destroys the measurement SRV object
*
* Function Scope \e Public.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
*/
void MacServices_measurementSRV_destroy( TI_HANDLE hMeasurementSRV );
/**
* \author Ronen Kalish\n
* \date 13-November-2005\n
* \brief Checks whether a beacon measurement is part of current measurement request
*
* Function Scope \e Private.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
* \return TI_TRUE if a beacon measurement is part of current request, TI_FALSE otherwise.\n
*/
TI_BOOL measurementSRVIsBeaconMeasureIncluded( TI_HANDLE hMeasurementSRV );
/**
* \author Ronen Kalish\n
* \date 15-November-2005\n
* \brief Finds the index for the measurement request with the shortest period
* (the one that has now completed).\n
*
* Function Scope \e Private.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
* \return index of the measurement request with the shortest duration.\n
*/
TI_INT32 measurementSRVFindMinDuration( TI_HANDLE hMeasurementSRV );
/**
* \author Ronen Kalish\n
* \date 15-November-2005\n
* \brief Handles an AP discovery timer expiry, by setting necessary values in the
* reply struct.\n
*
* Function Scope \e Private.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
* \param requestIndex - index of the beacon request in the request structure.\n
*/
void measurementSRVHandleBeaconMsrComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex );
/**
* \author Ronen Kalish\n
* \date 15-November-2005\n
* \brief Handles a channel load timer expiry, by requesting channel load
* results from the FW.\n
*
* Function Scope \e Private.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
* \param requestIndex - index of the channel load request in the request structure.\n
*/
void measurementSRVHandleChannelLoadComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex );
/**
* \author Ronen Kalish\n
* \date 15-November-2005\n
* \brief Handles a nois histogram timer expiry, by requesting noise histogram
* reaults from the FW.\n
*
* Function Scope \e Private.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
* \param requestIndex - indexof the beacon request in the request structure.\n
*/
void measurementSRVHandleNoiseHistogramComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex );
/**
* \author Ronen Kalish\n
* \date 16-November-2005\n
* \brief Checks whether all measuremtn types had completed and all param CBs had been called.\n
*
* Function Scope \e Public.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
* \param status - the get_param call status.\n
* \param CB_buf - pointer to the results buffer (already on the measurement SRV object)
*/
TI_BOOL measurementSRVIsMeasurementComplete( TI_HANDLE hMeasurementSRV );
/**
* \author Ronen Kalish\n
* \date 17-November-2005\n
* \brief Finds a measure type index in the measure request array.\n
*
* Function Scope \e Public.\n
* \param hMeasurementSRV - handle to the measurement SRV object.\n
* \param type - the measure type to look for.\n
* \return the type index, -1 if not found.\n
*/
TI_INT32 measurementSRVFindIndexByType( TI_HANDLE hMeasurementSRV, EMeasurementType type );
/****************************************************************************************
* measurementSRVRegisterFailureEventCB *
****************************************************************************************
DESCRIPTION: Registers a failure event callback for scan error notifications.
INPUT: - hMeasurementSRV - handle to the Measurement SRV object.
- failureEventCB - the failure event callback function.\n
- hFailureEventObj - handle to the object passed to the failure event callback function.
OUTPUT:
RETURN: void.
****************************************************************************************/
void measurementSRVRegisterFailureEventCB( TI_HANDLE hMeasurementSRV,
void * failureEventCB, TI_HANDLE hFailureEventObj );
void measurementSRV_restart( TI_HANDLE hMeasurementSRV);
#endif /* __MEASUREMENT_SRV_H__ */