1 /* 2 * roamingMngrApi.h 3 * 4 * Copyright(c) 1998 - 2010 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 roamingMngrApi.h 35 * \brief Internal Roaming Manager API 36 * 37 * \see roamingMngr.c 38 */ 39 40 /**************************************************************************** 41 * * 42 * MODULE: Roaming Manager * 43 * PURPOSE: Roaming Manager Module API * 44 * * 45 ****************************************************************************/ 46 47 #ifndef _ROAMING_MNGR_API_H_ 48 #define _ROAMING_MNGR_API_H_ 49 50 /*#include "802_11Defs.h"*/ 51 #include "osApi.h" 52 #include "paramOut.h" 53 #include "scanMngrApi.h" 54 #include "bssTypes.h" 55 #include "DrvMainModules.h" 56 #include "apConnApi.h" 57 /*-----------*/ 58 /* Constants */ 59 /*-----------*/ 60 61 #define MAX_ROAMING_TRIGGERS ROAMING_TRIGGER_LAST 62 63 64 /*--------------*/ 65 /* Enumerations */ 66 /*--------------*/ 67 68 /* Roaming Trigger groups, according to Roaming Triggers */ 69 typedef enum 70 { 71 ROAMING_TRIGGER_BG_SCAN_GROUP = ROAMING_TRIGGER_NORMAL_QUALITY_FOR_BG_SCAN, 72 ROAMING_TRIGGER_LOW_QUALITY_GROUP = ROAMING_TRIGGER_MAX_TX_RETRIES, 73 ROAMING_TRIGGER_FAST_CONNECT_GROUP = ROAMING_TRIGGER_SWITCH_CHANNEL, 74 ROAMING_TRIGGER_FULL_CONNECT_GROUP = ROAMING_TRIGGER_SECURITY_ATTACK 75 } roamingMngr_connectTypeGroup_e; 76 77 78 /*----------*/ 79 /* Typedefs */ 80 /*----------*/ 81 82 /* scan types */ 83 typedef enum 84 { 85 /* 0 */ ROAMING_NO_SCAN, 86 /* 1 */ ROAMING_PARTIAL_SCAN, 87 /* 2 */ ROAMING_PARTIAL_SCAN_RETRY, 88 /* 3 */ ROAMING_FULL_SCAN, 89 /* 4 */ ROAMING_FULL_SCAN_RETRY 90 91 } scan4RoamingType_e; 92 93 typedef struct 94 { 95 TI_UINT8 preAuthBSSList[MAX_SIZE_OF_BSS_TRACK_LIST]; 96 TI_UINT8 numOfPreAuthBSS; 97 TI_UINT8 neighborBSSList[MAX_SIZE_OF_BSS_TRACK_LIST]; 98 TI_UINT8 numOfNeighborBSS; 99 TI_UINT8 regularBSSList[MAX_SIZE_OF_BSS_TRACK_LIST]; 100 TI_UINT8 numOfRegularBSS; 101 } listOfCandidateAps_t; 102 103 104 struct _roamingMngr_t 105 { 106 /*** Roaming manager parameters that can be configured externally ***/ 107 roamingMngrConfig_t roamingMngrConfig; 108 roamingMngrThresholdsConfig_t roamingMngrThresholdsConfig; 109 TI_UINT32 lowPassFilterRoamingAttemptInMsec; 110 111 /*** Internal roaming parameters ***/ 112 apConn_roamingTrigger_e roamingTrigger; /* the roaming trigger type */ 113 TI_UINT32* pCurrentState; /* pointer to Roaming Generic SM current state */ 114 TI_BOOL maskRoamingEvents; /* Indicate if a trigger is already in process, and therefore the 115 other triggers will be ignored */ 116 TI_UINT32 lowQualityTriggerTimestamp; /* TS to filter Too many low Quality roaming triggers */ 117 scan4RoamingType_e scanType; /* the scan type performed for Roaming */ 118 bssList_t *pListOfAPs; /* list of BSS received from Scan Manager */ 119 TI_BOOL neighborApsExist; /* Indicating if Neighbor APs exist */ 120 listOfCandidateAps_t listOfCandidateAps; /* a list of the candiadte APs indexes in pListOfAPs according to 121 neighbor APs, pre-auth APs and other APs */ 122 TI_UINT8 candidateApIndex; /* The current candidate AP's index to Roam to */ 123 TI_BOOL handoverWasPerformed; /* Indicates whether at least one handover was performed */ 124 apConn_staCapabilities_t staCapabilities; 125 /* The station capabilities for the current Connection */ 126 TI_HANDLE hRoamingSm; /* Roaming manager SM handle */ 127 TI_INT8** RoamStateDescription; /* Roaming states index-name keyValue */ 128 TI_INT8** RoamEventDescription; /* Roaming Events index-name keyValue */ 129 130 131 /* Roaming manager handles to other objects */ 132 TI_HANDLE hReport; 133 TI_HANDLE hOs; 134 TI_HANDLE hScanMngr; 135 TI_HANDLE hAPConnection; 136 TI_HANDLE hTWD; 137 TI_HANDLE hEvHandler; 138 TI_HANDLE hCurrBss; 139 140 #ifdef TI_DBG 141 /* Debug trace for Roaming statistics */ 142 TI_UINT32 roamingTriggerEvents[MAX_ROAMING_TRIGGERS]; 143 TI_UINT32 roamingHandoverEvents[MAX_ROAMING_TRIGGERS]; 144 TI_UINT32 roamingSuccesfulHandoverNum; 145 TI_UINT32 roamingFailedHandoverNum; 146 TI_UINT32 roamingTriggerTimestamp; 147 TI_UINT32 roamingHandoverStartedTimestamp; 148 TI_UINT32 roamingHandoverCompletedTimestamp; 149 TI_UINT32 roamingAverageSuccHandoverDuration; 150 TI_UINT32 roamingAverageRoamingDuration; 151 #endif 152 153 TI_UINT8 RoamingOperationalMode; /* 0 - manual, 1 - auto*/ 154 TI_UINT8 bSendTspecInReassPkt; 155 TargetAp_t targetAP; /* holds the AP to connect with in manual mode */ 156 }; /* _roamingMngr_t */ 157 158 159 160 typedef struct _roamingMngr_t roamingMngr_t; 161 162 /*------------*/ 163 /* Structures */ 164 /*------------*/ 165 166 /*---------------------------*/ 167 /* External data definitions */ 168 /*---------------------------*/ 169 170 /*--------------------------------*/ 171 /* External functions definitions */ 172 /*--------------------------------*/ 173 174 /*----------------------------*/ 175 /* Global Function prototypes */ 176 /*----------------------------*/ 177 178 /** 179 * \brief Create the Roaming Manager context 180 * 181 * \param hOs - OS handler 182 * \return A pointer to the roaming manager handler on success, 183 * NULL on failure (unable to allocate memory or other system resource) 184 * 185 * \par Description 186 * Creates the Roaming Manager context: \n 187 * Allocate control block for preconfigured parameters and internal variables, create state-machine 188 * 189 * \sa roamingMngr_unload 190 */ 191 TI_HANDLE roamingMngr_create(TI_HANDLE hOs); 192 /** 193 * \brief Configure the Roaming Manager module 194 * 195 * \param pStadHandles - The driver modules handles 196 * \return void 197 * 198 * \par Description 199 * Configure the Roaming Manager module to do the following: 200 * - Initialize the Station broadcast key State Machine matrix 201 * - Store handlers of other modules (report module, Scan Manager, AP connection, TWD) 202 * - Initialize the roaming manager internal variables 203 * - Configure the roaming manager state-machine 204 * 205 * \sa 206 */ 207 void roamingMngr_init (TStadHandlesList *pStadHandles); 208 /** 209 * \brief Unloads the Roaming Manager Module 210 * 211 * \param hRoamingMngr - Roaming Manager handler 212 * \return TI_OK on success or TI_NOK on failure 213 * 214 * \par Description 215 * Unloads the components of the Roaming Manager module from memory: \n 216 * releases the allocation for the state-machine and internal variables 217 * 218 * \sa roamingMngr_create 219 */ 220 221 TI_STATUS roamingMngr_unload(TI_HANDLE hRoamingMngr); 222 /** 223 * \brief Get Roaming Manager parameters from the roamingMngr SM 224 * 225 * \param hRoamingMngr - Roaming Manager handler 226 * \param pParam - Output Parameters 227 * \return TI_OK on success or TI_NOK on failure 228 * 229 * \par Description 230 * 231 * \sa 232 */ 233 TI_STATUS roamingMngr_getParam(TI_HANDLE hRoamingMngr, paramInfo_t *pParam); 234 /** 235 * \brief Set Roaming Manager Module parameters to the roamingMngr SM 236 * 237 * \param hRoamingMngr - Roaming Manager handler 238 * \param pParam - Input Parameters 239 * \return TI_OK on success or TI_NOK on failure 240 * 241 * \par Description 242 * 243 * \sa 244 */ 245 TI_STATUS roamingMngr_setParam(TI_HANDLE hRoamingMngr, paramInfo_t *pParam); 246 /** 247 * \brief Indicates Roaming Manager that an Immediate Scan was completed 248 * and provides it with the Scan result 249 * 250 * \param hRoamingMngr - Handle to the roaming manager 251 * \param scanCmpltStatus - Scan complete reason 252 * \return TI_OK on success or TI_NOK on failure 253 * 254 * \par Description 255 * This procedure is called when the Scan Manager completed Immediate Scan for Roaming. 256 * It performs the following: 257 * - Partial or Full scan 258 * - Re-try Partial or Full scan if the previous scan failed 259 * - Full scan if the previous partial scan didn't get any APs 260 * - Fail event if all the Scans failed 261 * 262 * Algorithm description: 263 * - If Scan Complete is OK: 264 * ------------------------- 265 * - If APs found: 266 * - starts Selection 267 * - If NO APs found: 268 * - If Previous Scan was Partial: 269 * - Perform Full Scan 270 * - If Previous Scan was Full: 271 * - Report Error 272 * 273 * - If Scan Complete is NOT OK: 274 * ----------------------------- 275 * - Re-Try Scan 276 * - If APs found: 277 * - starts Selection 278 * - If NO APs found: 279 * - Re-Try Scan with current Scan Type (Partial/Full Scan Retry or No Scan) 280 * 281 * \sa 282 */ 283 TI_STATUS roamingMngr_immediateScanComplete(TI_HANDLE hRoamingMngr, scan_mngrResultStatus_e scanCmpltStatus); 284 /** 285 * \brief Indicates that a new BSSID is added to the BSS table 286 * 287 * \param hRoamingMngr - Handle to the roaming manager 288 * \param newBss_entry - List of BSSIDs that have been found 289 * \return TI_OK on success or TI_NOK on failure 290 * 291 * \par Description 292 * Indicates that a new BSSID is added to the BSS table (Called by the Scan Manager when new BSSID was found). 293 * This function triggers preauthentication to the new BSS. 294 * 295 * \sa 296 */ 297 TI_STATUS roamingMngr_updateNewBssList(TI_HANDLE hRoamingMngr, bssList_t *newBss_entry); 298 299 300 301 /* All functions below added by Lior*/ 302 303 TI_STATUS roamingMngr_setDefaults (TI_HANDLE hRoamingMngr, TRoamScanMngrInitParams *pInitParam); 304 TI_STATUS roamingMngr_setBssLossThreshold (TI_HANDLE hRoamingMngr, TI_UINT32 uNumOfBeacons, TI_UINT16 uClientID); 305 TI_STATUS roamingMngr_connect(TI_HANDLE hRoamingMngr, TargetAp_t* pTargetAp); 306 TI_STATUS roamingMngr_startImmediateScan(TI_HANDLE hRoamingMngr, channelList_t *pChannelList); 307 TI_STATUS roamingMngr_stopImmediateScan(TI_HANDLE hRoamingMngr); 308 TI_STATUS roamingMngr_immediateScanByAppComplete(TI_HANDLE hRoamingMngr, scan_mngrResultStatus_e scanCmpltStatus); 309 310 TI_STATUS roamingMngr_smEvent(TI_UINT8 event, void* data); 311 void roamingMngr_smStopWhileScanning(void *pData); 312 void roamingMngr_smStop(void *pData); 313 void roamingMngr_smUnexpected(void *pData); 314 void roamingMngr_smNop(void *pData); 315 316 317 #endif /* _ROAMING_MNGR_API_H_*/ 318 319