1 /* 2 * TWDriverScan.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 #ifndef TWDRIVERSCAN_H 35 #define TWDRIVERSCAN_H 36 37 /** \file TWDriverScan.h 38 * \brief TWDriver Scan APIs 39 * 40 * \see 41 */ 42 43 #include "tidef.h" 44 #include "TWDriverRate.h" 45 #include "public_commands.h" 46 47 /***************************************************************************************** 48 Scan Definitions 49 --------------- 50 This file is included by the TWDriver.h , it should not be included apart. !!!!!!! 51 *****************************************************************************************/ 52 53 54 /* 55 *********************************************************************** 56 * Constant definitions. 57 *********************************************************************** 58 */ 59 #define MAX_NUMBER_OF_CHANNELS_PER_SCAN 16 60 #define SCAN_MAX_NUM_OF_NORMAL_CHANNELS_PER_COMMAND MAX_NUMBER_OF_CHANNELS_PER_SCAN 61 #define SCAN_MAX_NUM_OF_SPS_CHANNELS_PER_COMMAND 16 62 #define SCAN_DEFAULT_MIN_CHANNEL_DWELL_TIME 30000 63 #define SCAN_DEFAULT_MAX_CHANNEL_DWELL_TIME 60000 64 #define SCAN_DEFAULT_EARLY_TERMINATION_EVENT SCAN_ET_COND_DISABLE 65 #define SCAN_DEFAULT_EARLY_TERMINATION_NUM_OF_FRAMES 0 66 67 #define PERIODIC_SCAN_MAX_SSID_NUM 8 68 #define PERIODIC_SCAN_MAX_INTERVAL_NUM 16 69 #define PERIODIC_SCAN_MAX_CHANNEL_NUM 37 /* G-14 + A-23 */ 70 71 #define MAX_SSID_LEN 32 72 73 /* 74 *********************************************************************** 75 * Enums. 76 *********************************************************************** 77 */ 78 /** \enum EScanType 79 * \brief Scan Type 80 * 81 * \par Description 82 * This Enumeration defines the available scan types. 83 * 84 * \sa TFileInfo 85 */ 86 typedef enum 87 { 88 /* 0 */ SCAN_TYPE_NORMAL_PASSIVE = 0, /**< Normal passive scan */ 89 /* 1 */ SCAN_TYPE_NORMAL_ACTIVE, /**< Normal active scan */ 90 /* 2 */ SCAN_TYPE_SPS, /**< Scheduled Passive scan */ 91 /* 3 */ SCAN_TYPE_TRIGGERED_PASSIVE, /**< Triggered Passive scan */ 92 /* 4 */ SCAN_TYPE_TRIGGERED_ACTIVE, /**< Triggered Active scan */ 93 /* 5 */ SCAN_TYPE_NO_SCAN, /**< No Scan to perform */ 94 /* 6 */ SCAN_TYPE_PACTSIVE /**< Passive + Active Scan (used for DFS - driver internal use only!!!) */ 95 96 } EScanType; 97 98 /** \enum EScanEtCondition 99 * \brief Scan Early Termonation Condition 100 * 101 * \par Description 102 * This Enumeration defines the different early termination causes. 103 * 104 * \sa TFileInfo 105 */ 106 typedef enum 107 { 108 SCAN_ET_COND_DISABLE = 0x00, /**< No early termination is not disabled (Do not perform an early termination scan)*/ 109 SCAN_ET_COND_BEACON = 0x10, /**< Early termination scan on beacon reception */ 110 SCAN_ET_COND_PROBE_RESP = 0x20, /**< Early termination scan on probe response reception */ 111 SCAN_ET_COND_ANY_FRAME = 0x30, /**< Early termination scan on both beacon or probe response reception */ 112 SCAN_ET_COND_NUM_OF_CONDS= 0x4 /**< Number of early termination conditions */ 113 114 } EScanEtCondition; 115 116 /** \enum EScanResultTag 117 * \brief Scan Debug Tags 118 * 119 * \par Description 120 * Enumeration of the differnet Scan Result Tags possible 121 * 122 * \sa 123 */ 124 typedef enum 125 { 126 /* 0 */ SCAN_RESULT_TAG_CURENT_BSS = 0, /**< */ 127 /* 1 */ SCAN_RESULT_TAG_APPLICATION_ONE_SHOT, /**< */ 128 /* 2 */ SCAN_RESULT_TAG_DRIVER_PERIODIC, /**< */ 129 /* 3 */ SCAN_RESULT_TAG_APPLICATION_PEIODIC, /**< */ 130 /* 4 */ SCAN_RESULT_TAG_MEASUREMENT, /**< */ 131 /* 5 */ SCAN_RESULT_TAG_IMMEDIATE, /**< */ 132 /* 6 */ SCAN_RESULT_TAG_CONTINUOUS, /**< */ 133 /* 7 */ SCAN_RESULT_TAG_MAX_NUMBER /**< */ 134 135 } EScanResultTag; 136 137 /** \enum ESsidVisability 138 * \brief SSID Visablility Type 139 * 140 * \par Description 141 * 142 * \sa 143 */ 144 typedef enum 145 { 146 /* 0 */ SCAN_SSID_VISABILITY_PUBLIC = 0, /**< Visible */ 147 /* 1 */ SCAN_SSID_VISABILITY_HIDDEN /**< Hidden */ 148 } ESsidVisability; 149 150 /*********************************************************************** 151 * Structure definitions. 152 *********************************************************************** 153 */ 154 /** \struct TSsid 155 * \brief SSID Parameters 156 * 157 * \par Description 158 * 159 * \sa 160 */ 161 typedef struct 162 { 163 TI_UINT8 len; /**< SSID Length */ 164 char str[ MAX_SSID_LEN ]; /**< SSID string buffer */ 165 166 } TSsid; 167 168 /** \struct TScanNormalChannelEntry 169 * \brief Scan Normal Channel Entry 170 * 171 * \par Description 172 * This structure defines single channel parameters for normal scan operation other than SPS (inc. triggered) 173 * 174 * \sa 175 */ 176 typedef struct 177 { 178 TMacAddr bssId; /**< BSSID (MAC address) to filter */ 179 TI_UINT32 maxChannelDwellTime; /**< Maximum time to stay on the channel if some frames were 180 * received but the early termination limit has not been reached (microseconds) 181 */ 182 TI_UINT32 minChannelDwellTime; /**< Minimum time to stay on the channel if no frames were received (microseconds) */ 183 EScanEtCondition earlyTerminationEvent; /**< Early termination frame type */ 184 TI_UINT8 ETMaxNumOfAPframes; /**< Number of frames from the early termination frame types according to the early 185 * Termination Event setting, after which scan is stopped on this channel 186 */ 187 TI_UINT8 txPowerDbm; /**< Power level used to transmit (for active scan only) (0: no change; 1-5: predefined power level */ 188 TI_UINT8 channel; /**< Channel to scan */ 189 190 } TScanNormalChannelEntry; 191 192 /** \struct TScanSpsChannelEntry 193 * \brief Scan SPS Channel Entry 194 * 195 * \par Description 196 * This structure defines single channel parameters for an SPS scan operation 197 * 198 * \sa 199 */ 200 typedef struct 201 { 202 TMacAddr bssId; /**< BSSID (source is MAC address) to filter */ 203 TI_UINT32 scanDuration; /**< Length of time to start scanning the channel (TSF lower 4 bytes) */ 204 TI_UINT32 scanStartTime; /**< Exact time to start scanning the channel (TSF lower 4 bytes) */ 205 EScanEtCondition earlyTerminationEvent; /**< Scan early termination frame type */ 206 TI_UINT8 ETMaxNumOfAPframes; /**< Number of frames from the early termination frame types according to 207 * the early Termination Event setting, after which scan is stopped on this channel 208 */ 209 TI_UINT8 channel; /**< Channel to scan */ 210 211 } TScanSpsChannelEntry; 212 213 /** \struct TScanChannelEntry 214 * \brief Scan Channel Entry 215 * 216 * \par Description 217 * Holds single channel parameters single-channel parameters for all scan types, 218 * either for normal scan or for SPS scan 219 * 220 * \sa 221 */ 222 typedef union 223 { 224 TScanNormalChannelEntry normalChannelEntry; /**< Normal scan parameters: channel parameters for all scan types other than SPS */ 225 TScanSpsChannelEntry SPSChannelEntry; /**< SPS scan parameters: channel parameters for SPS type */ 226 227 } TScanChannelEntry; 228 229 /** \struct TScanParams 230 * \brief scan operation parameters 231 * 232 * \par Description 233 * This structure defines parameters for a scan operation 234 * 235 * \sa 236 */ 237 typedef struct 238 { 239 TSsid desiredSsid; /**< The SSID to search (optional) */ 240 EScanType scanType; /**< Desired scan type (normal - active or passive, SPS, triggered - active or passive) */ 241 ERadioBand band; /**< Band to scan (A / BG) */ 242 TI_UINT8 probeReqNumber; /**< Number of probe requests to send on each channel (for active scan) */ 243 ERateMask probeRequestRate; /**< The rate at which to send the probe requests */ 244 TI_UINT8 Tid; /**< Time at which to trigger the scan (for triggered scan) */ 245 TI_UINT64 latestTSFValue; /**< For SPS scan: the latest TSF at which a frame was received. Used to detect 246 * TSF error (AP recovery). 247 */ 248 TI_UINT32 SPSScanDuration; /**< For SPS scan ONLY: the time duration of the scan (in milliseconds), used to 249 * Set timer according to. Used to set scan-complete timer 250 */ 251 TI_UINT8 numOfChannels; /**< Number of channels to scan */ 252 TScanChannelEntry channelEntry[ MAX_NUMBER_OF_CHANNELS_PER_SCAN ]; /**< Channel data array, actual size according to the above field. */ 253 254 } TScanParams; 255 256 /** \struct TPeriodicScanSsid 257 * \brief Periodic Scan SSID 258 * 259 * \par Description 260 * This structure defines parameters for Periodic scan for SSID 261 * 262 * \sa 263 */ 264 typedef struct 265 { 266 ESsidVisability eVisability; /**< Indicates if SSID Visible or not */ 267 TSsid tSsid; /**< The Parameters of Scaned SSID */ 268 } TPeriodicScanSsid; 269 270 /** \struct TPeriodicChannelEntry 271 * \brief Periodic Channel Entry 272 * 273 * \par Description 274 * This structure defines a Channel Entry of Periodic scan 275 * (each scanned channel has its own Channel Entry) 276 * 277 * \sa 278 */ 279 typedef struct 280 { 281 ERadioBand eBand; /**< Channel's Radio Band */ 282 TI_UINT32 uChannel; /**< Channel's Number */ 283 EScanType eScanType; /**< The Type of Scan Performed on the channel */ 284 TI_UINT32 uMinDwellTimeMs; /**< minimum time to dwell on the channel, in microseconds */ 285 TI_UINT32 uMaxDwellTimeMs; /**< maximum time to dwell on the channel, in microseconds */ 286 TI_UINT32 uTxPowerLevelDbm; /**< Channel's Power Level In Dbm/10 units */ 287 } TPeriodicChannelEntry; 288 289 /** \struct TPeriodicScanParams 290 * \brief Periodic Scan Parameters 291 * 292 * \par Description 293 * This structure defines all the parameters of Periodic scan 294 * 295 * \sa 296 */ 297 typedef struct 298 { 299 TI_UINT32 uSsidNum; /**< Number of Desired SSID scanned */ 300 TI_UINT8 uSsidListFilterEnabled; /** 1: eneable filtering according to the list; 0: disable */ 301 TPeriodicScanSsid tDesiredSsid[ PERIODIC_SCAN_MAX_SSID_NUM ]; /**< Buffer of size of maximum possible Periodic Scanned SSIDs. 302 * This buffer holds the Parameters of Desired SSIDs (for each SSID: 303 * visibility, length, string buffer) --> number of init entries in 304 * buffer: uSsidNum 305 */ 306 TI_UINT32 uCycleNum; /**< number of Scan cycles to run */ 307 TI_UINT32 uCycleIntervalMsec[ PERIODIC_SCAN_MAX_INTERVAL_NUM ]; /**< Intervals (in Msec) between two sequential scan cycle */ 308 TI_INT8 iRssiThreshold; /**< RSSI threshold */ 309 TI_INT8 iSnrThreshold; /**< SNR threshold */ 310 TI_UINT32 uFrameCountReportThreshold; /**< Report after N results are received */ 311 TI_BOOL bTerminateOnReport; /**< Indicates if to Terminate after report */ 312 ScanBssType_e eBssType; /**< Scan BSS Type */ 313 TI_UINT32 uProbeRequestNum; /**< Number of probe requests to transmit per SSID */ 314 TI_UINT32 uChannelNum; /**< Number of Scaned Channels */ 315 TPeriodicChannelEntry tChannels[ PERIODIC_SCAN_MAX_CHANNEL_NUM ]; /**< Buffer of size of maximum possible Periodic Scanned Channels. 316 * This buffer holds the Parameters of each Scanned Channel 317 */ 318 } TPeriodicScanParams; 319 320 #endif /* TWDRIVERSCAN_H */ 321 322 323 324 325 326