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