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                          ---------------
50This 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 */
85typedef 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 */
105typedef 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 */
123typedef 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 */
143typedef 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 */
160typedef 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 */
175typedef 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 */
199typedef 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 */
221typedef 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 */
236typedef 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 */
263typedef 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 */
278typedef 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 */
296typedef 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