1 /* 2 * ScanSrv.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 ScanSrv.h 35 * \brief This file include private definitions for the scan SRV module. 36 * 37 * \see ScanSrv.c, ScanSrvSM.c, ScanSrvSM.h 38 */ 39 40 41 #ifndef __SCANSRV_H__ 42 #define __SCANSRV_H__ 43 44 #include "TWDriverInternal.h" 45 #include "MacServices_api.h" 46 #include "fsm.h" 47 #include "ScanSrvSM.h" 48 49 /* 50 *********************************************************************** 51 * Constant definitions. 52 *********************************************************************** 53 */ 54 /* guard time for scan (added to calculated scan duration) */ 55 #define SCAN_SRV_FW_GUARD_TIME_MS 2000 56 /* module name for driver mode requests */ 57 #define SCAN_SRV_NAME "SSRV" 58 59 60 /* 61 *********************************************************************** 62 * Enums. 63 *********************************************************************** 64 */ 65 66 67 /* 68 *********************************************************************** 69 * Typedefs. 70 *********************************************************************** 71 */ 72 73 /* 74 *********************************************************************** 75 * Structure definitions. 76 *********************************************************************** 77 */ 78 79 /** \struct scanSRV_t 80 * \brief This structure contains the scan SRV object data 81 */ 82 typedef struct 83 { 84 TI_HANDLE hOS; /**< OS object handle */ 85 TI_HANDLE hReport; /**< report object handle */ 86 TI_HANDLE hPowerSrv; /**< power Server object handle */ 87 TI_HANDLE hTWD; /**< TWD layer handle */ 88 TI_HANDLE hTimer; /**< Timer module object handle */ 89 TI_HANDLE hEventMbox; /**< EventMbox module object handle */ 90 TI_HANDLE hCmdBld; /**< Command builder object handle */ 91 TScanSrvCompleteCb scanCompleteNotificationFunc; /**< 92 * upper layer (scan concentrator) scan complete 93 * callback function 94 */ 95 TI_HANDLE scanCompleteNotificationObj; /**< 96 * upper layer (scan concentrator) scan complete 97 * callback function 98 */ 99 100 TCmdResponseCb commandResponseFunc; /**< 101 * upper layer command response CB. Passed down into the HAL 102 * and called when the scan command has been received by the FW 103 */ 104 TI_HANDLE commandResponseObj; /**< 105 * object parameter passed to the commandResposeFunc by the HAL 106 * when it is called 107 */ 108 TFailureEventCb failureEventFunc; /**< 109 * upper layer Failure Event CB. 110 * called when the scan command has been Timer Expiry 111 */ 112 TI_HANDLE failureEventObj; /**< 113 * object parameter passed to the failureEventFunc 114 * when it is called 115 */ 116 TI_UINT16 SPSScanResult; /**< 117 * bitmap indicating which channels were scanned 118 * in an SPS scan 119 */ 120 TI_BOOL bTSFError; /** indicates whether a TSF error occured */ /**< 121 * scan result: indicates a TSF error event and 122 * which channels were scanned in SPS 123 */ 124 TI_BOOL bDtimOverlapping; /**< Indicates whether the scan is overlapping DTIM */ 125 TI_BOOL bExitFromDriverMode; /**< 126 * Indicates whether to exit driver mode once scan 127 * is finished 128 */ 129 TI_BOOL bSendNullData; /**< 130 * Indicates whether to send Null data when exiting driver 131 * mode once scan is finished 132 */ 133 TI_BOOL bScanOnDriverModeFailure; /**< 134 * Indicates whether to scan if driver mode entry 135 * wasn't successful 136 */ 137 TI_BOOL bHighPriority; /**< 138 * Indicates whether to request high priority 139 * (overlapping DTIM) scan 140 */ 141 TI_BOOL bSPSScan; /**< 142 * whether the running scan type is SPS (TI_TRUE) 143 * or something else (TI_FALSE). Used to stop a 144 * running scan. 145 */ 146 TScanParams* scanParams; /**< scan parameters */ 147 EScanResultTag eScanTag; /**< scan result tag */ 148 TI_UINT32 uResultCount; /**< number of scan results (received from the FW) */ 149 TI_HANDLE hScanSrvTimer; /**< scan operation timer */ 150 TI_BOOL bTimerRunning; /**< whether the above timer is running */ 151 TI_BOOL bInRequest; /**< 152 * Indicates whether the SM is run within 153 * the scan request context (if so, to avoid 154 * re-entrance, the complete function shouldn't 155 * be called on failure, but rather an invalid 156 * status should be returned) 157 */ 158 TI_STATUS returnStatus; /**< 159 * Holds the return code to the upper layer 160 * Used to save errors during SM operation. 161 */ 162 /* state machine */ 163 fsm_stateMachine_t* SM; /**< 164 * state machines for different 165 * scan types 166 */ 167 scan_SRVSMStates_e SMState; /**< 168 * state machine current states 169 * for different scan types 170 */ 171 E80211PsMode psRequest; /**< 172 * Indicates if PS was requested or not 173 * for current scan 174 */ 175 TI_UINT32 numberOfNoScanCompleteToRecovery; 176 /**< 177 * The number of consecutive no scan complete 178 * that will trigger a recovery notification 179 */ 180 TI_UINT32 currentNumberOfConsecutiveNoScanCompleteEvents; 181 /**< 182 * The number of consecutivre no scan complete 183 * events at present 184 */ 185 TI_BOOL bNoScanCompleteFlag; /**< 186 * Indicates if the last event was start scan 187 * (true) or no scan complete (false) to be able 188 * to nullify correctly the above counter */ 189 TI_UINT32 uTriggeredScanTimeOut; /**< 190 * Time out for starting triggered scan between 191 * 2 channels */ 192 TI_UINT8 uDtimPeriod; 193 TI_UINT16 uBeaconInterval; 194 } scanSRV_t; 195 196 /* 197 *********************************************************************** 198 * External data definitions. 199 *********************************************************************** 200 */ 201 202 /* 203 *********************************************************************** 204 * External functions definitions 205 *********************************************************************** 206 */ 207 208 /** 209 * \author Yuval Adler\n 210 * \date 16-Oct-2004\n 211 * \brief Creates the scan SRV object 212 * 213 * Function Scope \e Public.\n 214 * \param hOS - handle to the OS object.\n 215 * \return a handle to the scan SRV object, NULL if an error occurred.\n 216 */ 217 TI_HANDLE MacServices_scanSRV_create( TI_HANDLE hOS ); 218 219 /** 220 * \author Yuval Adler\n 221 * \date 29-Dec-2004\n 222 * \brief Finalizes the scan SRV module (releasing memory and timer) 223 * 224 * Function Scope \e Public.\n 225 * \param hScanSRV - handle to the scan SRV object.\n 226 */ 227 void MacServices_scanSRV_destroy( TI_HANDLE hScanSRV ); 228 229 /** 230 * \author Yuval Adler\n 231 * \date 29-Dec-2004\n 232 * \brief Initializes the scan SRV module, registers SCAN_COMPLETE to HAL. 233 * 234 * Function Scope \e Public.\n 235 * \param hScanSRV - handle to the scan SRV object.\n 236 * \param Handles of other modules.\n 237 */ 238 TI_STATUS MacServices_scanSRV_init (TI_HANDLE hMacServices, 239 TI_HANDLE hReport, 240 TI_HANDLE hTWD, 241 TI_HANDLE hTimer, 242 TI_HANDLE hEventMbox, 243 TI_HANDLE hCmdBld); 244 245 /** 246 * \author Ronen Kalish\n 247 * \date 26-July-2006\n 248 * \brief Configures the scan SRV module with initialization values 249 * 250 * Function Scope \e Public.\n 251 * \param hScanSRV - handle to the scan SRV object.\n 252 * \param hReport - handle to the report object.\n 253 * \param hHalCtrl - handle to the HAL ctrl object.\n 254 */ 255 void MacServices_scanSrv_config( TI_HANDLE hMacServices, TScanSrvInitParams* pInitParams ); 256 257 /** 258 * \author Ronen Kalish\n 259 * \date 29-Dec-2004\n 260 * \brief Calculates the maximal time required for a scan operation 261 * 262 * Function Scope \e Public.\n 263 * \param hScanSRV - handle to the scan SRV object.\n 264 * \param scanParams - the scan parameters 265 * \param bConsiderDTIM - whether this scan overlaps DTIM 266 * \return the time (in milliseconds) 267 */ 268 TI_UINT32 MacServices_scanSRVcalculateScanTimeout( TI_HANDLE hScanSrv, TScanParams* scanParams, TI_BOOL bConsiderDTIM ); 269 270 /** 271 * \author Ronen Kalish\n 272 * \date 16-Jan-2005\n 273 * \brief Convert time units (1024 usecs) to millisecs 274 * 275 * Function Scope \e Private.\n 276 * \param tu - the time in time units 277 * \return the time in milliseconds 278 */ 279 TI_UINT32 MacServices_scanSRVConvertTUToMsec( TI_UINT32 tu ); 280 281 /** 282 * \author Yuval Adler\n 283 * \date 27-Sep-2005\n 284 * \brief This function is the CB which is called as response to 'StartScan' or 'StopScan' \n. 285 * here we check if there is a GWSI command response , and call it if necessary .\n 286 * Function Scope \e Private.\n 287 * \param hScanSrv - handle to the scan SRV object.\n 288 * \param MboxStatus - mailbox status. \n 289 */ 290 291 void MacServices_scanSRVCommandMailBoxCB(TI_HANDLE hScanSrv,TI_UINT16 MboxStatus); 292 293 294 /** 295 * \brief Registers a failure event callback for scan error notifications. 296 * 297 * Function Scope \e Public.\n 298 * \param hMacServices - handle to the MacServices object.\n 299 * \param failureEventCB - the failure event callback function.\n 300 * \param hFailureEventObj - handle to the object passed to the failure event callback function.\n 301 */ 302 void scanSRV_registerFailureEventCB( TI_HANDLE hScanSRV, 303 void * failureEventCB, TI_HANDLE hFailureEventObj ); 304 305 void scanSRV_restart( TI_HANDLE hScanSRV); 306 307 308 #endif /* __SCANSRV_H__ */ 309
