1 /* 2 * MeasurementSrv.h 3 * 4 * Copyright(c) 1998 - 2009 Texas Instruments. All rights reserved. 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * * Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * * Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * * Neither the name Texas Instruments nor the names of its 18 * contributors may be used to endorse or promote products derived 19 * from this software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 */ 33 34 /** \file MeasurementSrv.h 35 * \brief This file include private definitions for the Measurement SRV module. 36 * \author Ronen Kalish 37 * \date 08-November-2005 38 */ 39 40 #ifndef __MEASUREMENT_SRV_H__ 41 #define __MEASUREMENT_SRV_H__ 42 43 #include "TWDriverInternal.h" 44 #include "MacServices_api.h" 45 #include "fsm.h" 46 #include "MeasurementSrvSM.h" 47 48 /* 49 *********************************************************************** 50 * Constant definitions. 51 *********************************************************************** 52 */ 53 /* Time in milliseconds to receive a command complete for measure start / stop from the FW */ 54 #define MSR_FW_GUARD_TIME 100 55 #define DEF_SAMPLE_INTERVAL (100) /* expressed in microsec */ 56 #define NOISE_HISTOGRAM_THRESHOLD 100 57 /* Get param callback flags */ 58 #define MSR_SRV_WAITING_CHANNEL_LOAD_RESULTS 0x01 /* channel load results are still pending */ 59 #define MSR_SRV_WAITING_NOISE_HIST_RESULTS 0x02 /* noise histogram results are still pending */ 60 61 /* 62 *********************************************************************** 63 * Enums. 64 *********************************************************************** 65 */ 66 67 68 /* 69 *********************************************************************** 70 * Typedefs. 71 *********************************************************************** 72 */ 73 74 /* 75 *********************************************************************** 76 * Structure definitions. 77 *********************************************************************** 78 */ 79 80 /** \struct measurementSRV_t 81 * \brief This structure contains the measurement SRV object data 82 */ 83 typedef struct 84 { 85 TMediumOccupancy mediumOccupancyResults; /**< channel load results buffer */ 86 TNoiseHistogramResults noiseHistogramResults; /**< noise histogram results buffer */ 87 88 /* module handles */ 89 TI_HANDLE hOS; /**< OS object handle */ 90 TI_HANDLE hReport; /**< report object handle */ 91 TI_HANDLE hPowerSaveSRV; /**< power save SRV object handle */ 92 TI_HANDLE hCmdBld; /**< Command Builder object handle */ 93 TI_HANDLE hEventMbox; /**< Event Mbox handle */ 94 TI_HANDLE hTimer ; /**< Timer Module handle */ 95 /* CB functions and objects */ 96 TMeasurementSrvCompleteCb measurmentCompleteCBFunc; 97 /**< 98 * upper layer (measurement manager) measurement complete 99 * callback function 100 */ 101 TI_HANDLE measurementCompleteCBObj; /**< 102 * upper layer (measurement manager) measurement complete 103 * callback object 104 */ 105 106 TCmdResponseCb commandResponseCBFunc; /**< 107 * upper layer command response CB, used for both start 108 * and stop. Passed down to the HAL and called when 109 * the measurement command has been received by the FW 110 */ 111 TI_HANDLE commandResponseCBObj; /**< 112 * object parameter passed to the commandResposeFunc by 113 * the HAL when it is called 114 */ 115 116 TFailureEventCb failureEventFunc; /**< 117 * upper layer Failure Event CB. 118 * called when the scan command has been Timer Expiry 119 */ 120 TI_HANDLE failureEventObj; /**< 121 * object parameter passed to the failureEventFunc 122 * when it is called 123 */ 124 /* Timers */ 125 TI_HANDLE hRequestTimer[ MAX_NUM_OF_MSR_TYPES_IN_PARALLEL ]; 126 /**< Timers for different measurement types */ 127 TI_BOOL bRequestTimerRunning[ MAX_NUM_OF_MSR_TYPES_IN_PARALLEL ]; 128 /**< Indicates whether each request timer is running */ 129 TI_HANDLE hStartStopTimer; /**< Timer for start / stop commands guard */ 130 TI_BOOL bStartStopTimerRunning; /**< 131 * Indicates whether the start / stop command guard 132 * timer is running 133 */ 134 /* Misc stuff */ 135 TI_BOOL bInRequest; /**< 136 * Indicates whether the SM is run within 137 * the measurement request context (if so, to avoid 138 * re-entrance, the complete function shouldn't 139 * be called on failure, but rather an invalid 140 * status should be returned) 141 */ 142 TI_STATUS returnStatus; /**< 143 * Holds the return code to the upper layer 144 * Used to save errors during SM operation. 145 */ 146 TI_BOOL bSendNullDataWhenExitPs; /**< whether to send NULL data frame when exiting 147 * driver mode 148 */ 149 /* state machine */ 150 fsm_stateMachine_t* SM; /**< 151 * state machines for different 152 * scan types 153 */ 154 measurements_SRVSMStates_e SMState; /**< state machine current states */ 155 /* measurement request */ 156 TMeasurementRequest msrRequest; /**< measurement request parameters */ 157 TMeasurementReply msrReply; /**< measurement reply values */ 158 TI_UINT32 requestRecptionTimeStampMs; /**< The time in which the request was received. */ 159 TI_UINT32 timeToRequestExpiryMs; /**< 160 * The duration (in ms) from request receiption 161 * until it should actually start. Request is 162 * discarded if a longer period is required 163 */ 164 TI_UINT8 pendingParamCBs; /**< 165 * a bitmap indicating which get_param CBs are 166 * currently pending (noise histogram and/or 167 * channel load). 168 */ 169 } measurementSRV_t; 170 171 /* 172 *********************************************************************** 173 * External data definitions. 174 *********************************************************************** 175 */ 176 177 /* 178 *********************************************************************** 179 * External functions definitions 180 *********************************************************************** 181 */ 182 183 /** 184 * \author Ronen Kalish\n 185 * \date 08-November-2005\n 186 * \brief Creates the measurement SRV object 187 * 188 * Function Scope \e Public.\n 189 * \param hOS - handle to the OS object.\n 190 * \return a handle to the measurement SRV object, NULL if an error occurred.\n 191 */ 192 TI_HANDLE MacServices_measurementSRV_create( TI_HANDLE hOS ); 193 194 /** 195 * \author Ronen Kalish\n 196 * \date 08-November-2005\n 197 * \brief Initializes the measurement SRV object 198 * 199 * Function Scope \e Public.\n 200 * \param hMeasurementSRV - handle to the measurement SRV object.\n 201 * \param hReport - handle to the report object.\n 202 * \param hCmdBld - handle to the Command Builder object.\n 203 * \param hEventMbox - handle to the Event Mbox object.\n 204 * \param hPowerSaveSRV - handle to the power save SRV object.\n 205 * \param hTimer - handle to the Timer module object.\n 206 */ 207 TI_STATUS MacServices_measurementSRV_init (TI_HANDLE hMeasurementSRV, 208 TI_HANDLE hReport, 209 TI_HANDLE hCmdBld, 210 TI_HANDLE hEventMbox, 211 TI_HANDLE hPowerSaveSRV, 212 TI_HANDLE hTimer); 213 214 /** 215 * \author Ronen Kalish\n 216 * \date 08-November-2005\n 217 * \brief Destroys the measurement SRV object 218 * 219 * Function Scope \e Public.\n 220 * \param hMeasurementSRV - handle to the measurement SRV object.\n 221 */ 222 void MacServices_measurementSRV_destroy( TI_HANDLE hMeasurementSRV ); 223 224 /** 225 * \author Ronen Kalish\n 226 * \date 13-November-2005\n 227 * \brief Checks whether a beacon measurement is part of current measurement request 228 * 229 * Function Scope \e Private.\n 230 * \param hMeasurementSRV - handle to the measurement SRV object.\n 231 * \return TI_TRUE if a beacon measurement is part of current request, TI_FALSE otherwise.\n 232 */ 233 TI_BOOL measurementSRVIsBeaconMeasureIncluded( TI_HANDLE hMeasurementSRV ); 234 235 /** 236 * \author Ronen Kalish\n 237 * \date 15-November-2005\n 238 * \brief Finds the index for the measurement request with the shortest period 239 * (the one that has now completed).\n 240 * 241 * Function Scope \e Private.\n 242 * \param hMeasurementSRV - handle to the measurement SRV object.\n 243 * \return index of the measurement request with the shortest duration.\n 244 */ 245 TI_INT32 measurementSRVFindMinDuration( TI_HANDLE hMeasurementSRV ); 246 247 /** 248 * \author Ronen Kalish\n 249 * \date 15-November-2005\n 250 * \brief Handles an AP discovery timer expiry, by setting necessary values in the 251 * reply struct.\n 252 * 253 * Function Scope \e Private.\n 254 * \param hMeasurementSRV - handle to the measurement SRV object.\n 255 * \param requestIndex - index of the beacon request in the request structure.\n 256 */ 257 void measurementSRVHandleBeaconMsrComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex ); 258 259 /** 260 * \author Ronen Kalish\n 261 * \date 15-November-2005\n 262 * \brief Handles a channel load timer expiry, by requesting channel load 263 * results from the FW.\n 264 * 265 * Function Scope \e Private.\n 266 * \param hMeasurementSRV - handle to the measurement SRV object.\n 267 * \param requestIndex - index of the channel load request in the request structure.\n 268 */ 269 void measurementSRVHandleChannelLoadComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex ); 270 271 /** 272 * \author Ronen Kalish\n 273 * \date 15-November-2005\n 274 * \brief Handles a nois histogram timer expiry, by requesting noise histogram 275 * reaults from the FW.\n 276 * 277 * Function Scope \e Private.\n 278 * \param hMeasurementSRV - handle to the measurement SRV object.\n 279 * \param requestIndex - indexof the beacon request in the request structure.\n 280 */ 281 void measurementSRVHandleNoiseHistogramComplete( TI_HANDLE hMeasurementSRV, TI_INT32 requestIndex ); 282 283 /** 284 * \author Ronen Kalish\n 285 * \date 16-November-2005\n 286 * \brief Checks whether all measuremtn types had completed and all param CBs had been called.\n 287 * 288 * Function Scope \e Public.\n 289 * \param hMeasurementSRV - handle to the measurement SRV object.\n 290 * \param status - the get_param call status.\n 291 * \param CB_buf - pointer to the results buffer (already on the measurement SRV object) 292 */ 293 TI_BOOL measurementSRVIsMeasurementComplete( TI_HANDLE hMeasurementSRV ); 294 295 /** 296 * \author Ronen Kalish\n 297 * \date 17-November-2005\n 298 * \brief Finds a measure type index in the measure request array.\n 299 * 300 * Function Scope \e Public.\n 301 * \param hMeasurementSRV - handle to the measurement SRV object.\n 302 * \param type - the measure type to look for.\n 303 * \return the type index, -1 if not found.\n 304 */ 305 TI_INT32 measurementSRVFindIndexByType( TI_HANDLE hMeasurementSRV, EMeasurementType type ); 306 307 /**************************************************************************************** 308 * measurementSRVRegisterFailureEventCB * 309 **************************************************************************************** 310 DESCRIPTION: Registers a failure event callback for scan error notifications. 311 312 313 INPUT: - hMeasurementSRV - handle to the Measurement SRV object. 314 - failureEventCB - the failure event callback function.\n 315 - hFailureEventObj - handle to the object passed to the failure event callback function. 316 317 OUTPUT: 318 RETURN: void. 319 ****************************************************************************************/ 320 void measurementSRVRegisterFailureEventCB( TI_HANDLE hMeasurementSRV, 321 void * failureEventCB, TI_HANDLE hFailureEventObj ); 322 323 void measurementSRV_restart( TI_HANDLE hMeasurementSRV); 324 325 326 #endif /* __MEASUREMENT_SRV_H__ */ 327 328