diff -r 000000000000 -r 10c42ec6c05f TWD/MacServices/MeasurementSrv.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/TWD/MacServices/MeasurementSrv.h Tue Jun 29 12:34:26 2010 +0100 @@ -0,0 +1,332 @@ +/* + * 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__ */ +