1 /*- 2 * Copyright (c) 2005-2009 Sam Leffler, Errno Consulting 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24 * 25 * $FreeBSD: head/sys/net80211/ieee80211_scan.h 195618 2009-07-11 15:02:45Z rpaulo $ 26 * $DragonFly$ 27 */ 28 #ifndef _NET80211_IEEE80211_SCAN_H_ 29 #define _NET80211_IEEE80211_SCAN_H_ 30 31 /* 32 * 802.11 scanning support. 33 * 34 * Scanning is the procedure by which a station locates a bss to join 35 * (infrastructure/ibss mode), or a channel to use (when operating as 36 * an ap or ibss master). Scans are either "active" or "passive". An 37 * active scan causes one or more probe request frames to be sent on 38 * visiting each channel. A passive request causes each channel in the 39 * scan set to be visited but no frames to be transmitted; the station 40 * only listens for traffic. Note that active scanning may still need 41 * to listen for traffic before sending probe request frames depending 42 * on regulatory constraints; the 802.11 layer handles this by generating 43 * a callback when scanning on a ``passive channel'' when the 44 * IEEE80211_FEXT_PROBECHAN flag is set. 45 * 46 * A scan operation involves constructing a set of channels to inspect 47 * (the scan set), visiting each channel and collecting information 48 * (e.g. what bss are present), and then analyzing the results to make 49 * decisions like which bss to join. This process needs to be as fast 50 * as possible so we do things like intelligently construct scan sets 51 * and dwell on a channel only as long as necessary. The scan code also 52 * maintains a cache of recent scan results and uses it to bypass scanning 53 * whenever possible. The scan cache is also used to enable roaming 54 * between access points when operating in infrastructure mode. 55 * 56 * Scanning is handled with pluggable modules that implement "policy" 57 * per-operating mode. The core scanning support provides an 58 * instrastructure to support these modules and exports a common api 59 * to the rest of the 802.11 layer. Policy modules decide what 60 * channels to visit, what state to record to make decisions (e.g. ap 61 * mode scanning for auto channel selection keeps significantly less 62 * state than sta mode scanning for an ap to associate to), and selects 63 * the final station/channel to return as the result of a scan. 64 * 65 * Scanning is done synchronously when initially bringing a vap to an 66 * operational state and optionally in the background to maintain the 67 * scan cache for doing roaming and rogue ap monitoring. Scanning is 68 * not tied to the 802.11 state machine that governs vaps though there 69 * is linkage to the IEEE80211_SCAN state. Only one vap at a time may 70 * be scanning; this scheduling policy is handled in ieee80211_new_state 71 * and is invisible to the scanning code. 72 */ 73 #define IEEE80211_SCAN_MAX IEEE80211_CHAN_MAX 74 75 struct ieee80211_scanner; /* scan policy state */ 76 77 struct ieee80211_scan_ssid { 78 int len; /* length in bytes */ 79 uint8_t ssid[IEEE80211_NWID_LEN]; /* ssid contents */ 80 }; 81 #define IEEE80211_SCAN_MAX_SSID 1 /* max # ssid's to probe */ 82 83 /* 84 * Scan state visible to the 802.11 layer. Scan parameters and 85 * results are stored in this data structure. The ieee80211_scan_state 86 * structure is extended with space that is maintained private to 87 * the core scanning support. We allocate one instance and link it 88 * to the ieee80211com structure; then share it between all associated 89 * vaps. We could allocate multiple of these, e.g. to hold multiple 90 * scan results, but this is sufficient for current needs. 91 */ 92 struct ieee80211_scan_state { 93 struct ieee80211vap *ss_vap; 94 struct ieee80211com *ss_ic; 95 const struct ieee80211_scanner *ss_ops; /* policy hookup, see below */ 96 void *ss_priv; /* scanner private state */ 97 uint16_t ss_flags; 98 #define IEEE80211_SCAN_NOPICK 0x0001 /* scan only, no selection */ 99 #define IEEE80211_SCAN_ACTIVE 0x0002 /* active scan (probe req) */ 100 #define IEEE80211_SCAN_PICK1ST 0x0004 /* ``hey sailor'' mode */ 101 #define IEEE80211_SCAN_BGSCAN 0x0008 /* bg scan, exit ps at end */ 102 #define IEEE80211_SCAN_ONCE 0x0010 /* do one complete pass */ 103 #define IEEE80211_SCAN_NOBCAST 0x0020 /* no broadcast probe req */ 104 #define IEEE80211_SCAN_NOJOIN 0x0040 /* no auto-sequencing */ 105 #define IEEE80211_SCAN_GOTPICK 0x1000 /* got candidate, can stop */ 106 uint8_t ss_nssid; /* # ssid's to probe/match */ 107 struct ieee80211_scan_ssid ss_ssid[IEEE80211_SCAN_MAX_SSID]; 108 /* ssid's to probe/match */ 109 /* ordered channel set */ 110 struct ieee80211_channel *ss_chans[IEEE80211_SCAN_MAX]; 111 uint16_t ss_next; /* ix of next chan to scan */ 112 uint16_t ss_last; /* ix+1 of last chan to scan */ 113 unsigned long ss_mindwell; /* min dwell on channel */ 114 unsigned long ss_maxdwell; /* max dwell on channel */ 115 }; 116 117 /* 118 * The upper 16 bits of the flags word is used to communicate 119 * information to the scanning code that is NOT recorded in 120 * ss_flags. It might be better to split this stuff out into 121 * a separate variable to avoid confusion. 122 */ 123 #define IEEE80211_SCAN_FLUSH 0x00010000 /* flush candidate table */ 124 #define IEEE80211_SCAN_NOSSID 0x80000000 /* don't update ssid list */ 125 126 struct ieee80211com; 127 void ieee80211_scan_attach(struct ieee80211com *); 128 void ieee80211_scan_detach(struct ieee80211com *); 129 void ieee80211_scan_vattach(struct ieee80211vap *); 130 void ieee80211_scan_vdetach(struct ieee80211vap *); 131 132 void ieee80211_scan_dump_channels(const struct ieee80211_scan_state *); 133 134 #define IEEE80211_SCAN_FOREVER 0x7fffffff 135 int ieee80211_start_scan(struct ieee80211vap *, int flags, 136 u_int duration, u_int mindwell, u_int maxdwell, 137 u_int nssid, const struct ieee80211_scan_ssid ssids[]); 138 int ieee80211_check_scan(struct ieee80211vap *, int flags, 139 u_int duration, u_int mindwell, u_int maxdwell, 140 u_int nssid, const struct ieee80211_scan_ssid ssids[]); 141 int ieee80211_check_scan_current(struct ieee80211vap *); 142 int ieee80211_bg_scan(struct ieee80211vap *, int); 143 void ieee80211_cancel_scan(struct ieee80211vap *); 144 void ieee80211_cancel_anyscan(struct ieee80211vap *); 145 void ieee80211_scan_next(struct ieee80211vap *); 146 void ieee80211_scan_done(struct ieee80211vap *); 147 void ieee80211_probe_curchan(struct ieee80211vap *, int); 148 struct ieee80211_channel *ieee80211_scan_pickchannel(struct ieee80211com *, int); 149 150 struct ieee80211_scanparams; 151 void ieee80211_add_scan(struct ieee80211vap *, 152 const struct ieee80211_scanparams *, 153 const struct ieee80211_frame *, 154 int subtype, int rssi, int noise); 155 void ieee80211_scan_timeout(struct ieee80211com *); 156 157 void ieee80211_scan_assoc_success(struct ieee80211vap *, 158 const uint8_t mac[IEEE80211_ADDR_LEN]); 159 enum { 160 IEEE80211_SCAN_FAIL_TIMEOUT = 1, /* no response to mgmt frame */ 161 IEEE80211_SCAN_FAIL_STATUS = 2 /* negative response to " " */ 162 }; 163 void ieee80211_scan_assoc_fail(struct ieee80211vap *, 164 const uint8_t mac[IEEE80211_ADDR_LEN], int reason); 165 void ieee80211_scan_flush(struct ieee80211vap *); 166 167 struct ieee80211_scan_entry; 168 typedef void ieee80211_scan_iter_func(void *, 169 const struct ieee80211_scan_entry *); 170 void ieee80211_scan_iterate(struct ieee80211vap *, 171 ieee80211_scan_iter_func, void *); 172 enum { 173 IEEE80211_BPARSE_BADIELEN = 0x01, /* ie len past end of frame */ 174 IEEE80211_BPARSE_RATES_INVALID = 0x02, /* invalid RATES ie */ 175 IEEE80211_BPARSE_XRATES_INVALID = 0x04, /* invalid XRATES ie */ 176 IEEE80211_BPARSE_SSID_INVALID = 0x08, /* invalid SSID ie */ 177 IEEE80211_BPARSE_CHAN_INVALID = 0x10, /* invalid FH/DSPARMS chan */ 178 IEEE80211_BPARSE_OFFCHAN = 0x20, /* DSPARMS chan != curchan */ 179 IEEE80211_BPARSE_BINTVAL_INVALID= 0x40, /* invalid beacon interval */ 180 IEEE80211_BPARSE_CSA_INVALID = 0x80, /* invalid CSA ie */ 181 }; 182 183 /* 184 * Parameters supplied when adding/updating an entry in a 185 * scan cache. Pointer variables should be set to NULL 186 * if no data is available. Pointer references can be to 187 * local data; any information that is saved will be copied. 188 * All multi-byte values must be in host byte order. 189 */ 190 struct ieee80211_scanparams { 191 uint8_t status; /* bitmask of IEEE80211_BPARSE_* */ 192 uint8_t chan; /* channel # from FH/DSPARMS */ 193 uint8_t bchan; /* curchan's channel # */ 194 uint8_t fhindex; 195 uint16_t fhdwell; /* FHSS dwell interval */ 196 uint16_t capinfo; /* 802.11 capabilities */ 197 uint16_t erp; /* NB: 0x100 indicates ie present */ 198 uint16_t bintval; 199 uint8_t timoff; 200 uint8_t *ies; /* all captured ies */ 201 size_t ies_len; /* length of all captured ies */ 202 uint8_t *tim; 203 uint8_t *tstamp; 204 uint8_t *country; 205 uint8_t *ssid; 206 uint8_t *rates; 207 uint8_t *xrates; 208 uint8_t *doth; 209 uint8_t *wpa; 210 uint8_t *rsn; 211 uint8_t *wme; 212 uint8_t *htcap; 213 uint8_t *htinfo; 214 uint8_t *ath; 215 uint8_t *tdma; 216 uint8_t *csa; 217 uint8_t *meshid; 218 uint8_t *meshconf; 219 uint8_t *spare[3]; 220 }; 221 222 /* 223 * Scan cache entry format used when exporting data from a policy 224 * module; this data may be represented some other way internally. 225 */ 226 struct ieee80211_scan_entry { 227 uint8_t se_macaddr[IEEE80211_ADDR_LEN]; 228 uint8_t se_bssid[IEEE80211_ADDR_LEN]; 229 /* XXX can point inside se_ies */ 230 uint8_t se_ssid[2+IEEE80211_NWID_LEN]; 231 uint8_t se_rates[2+IEEE80211_RATE_MAXSIZE]; 232 uint8_t se_xrates[2+IEEE80211_RATE_MAXSIZE]; 233 union { 234 uint8_t data[8]; 235 u_int64_t tsf; 236 } se_tstamp; /* from last rcv'd beacon */ 237 uint16_t se_intval; /* beacon interval (host byte order) */ 238 uint16_t se_capinfo; /* capabilities (host byte order) */ 239 struct ieee80211_channel *se_chan;/* channel where sta found */ 240 uint16_t se_timoff; /* byte offset to TIM ie */ 241 uint16_t se_fhdwell; /* FH only (host byte order) */ 242 uint8_t se_fhindex; /* FH only */ 243 uint8_t se_dtimperiod; /* DTIM period */ 244 uint16_t se_erp; /* ERP from beacon/probe resp */ 245 int8_t se_rssi; /* avg'd recv ssi */ 246 int8_t se_noise; /* noise floor */ 247 uint8_t se_cc[2]; /* captured country code */ 248 uint8_t se_meshid[2+IEEE80211_MESHID_LEN]; 249 struct ieee80211_ies se_ies; /* captured ie's */ 250 u_int se_age; /* age of entry (0 on create) */ 251 }; 252 MALLOC_DECLARE(M_80211_SCAN); 253 254 /* 255 * Template for an in-kernel scan policy module. 256 * Modules register with the scanning code and are 257 * typically loaded as needed. 258 */ 259 struct ieee80211_scanner { 260 const char *scan_name; /* printable name */ 261 int (*scan_attach)(struct ieee80211_scan_state *); 262 int (*scan_detach)(struct ieee80211_scan_state *); 263 int (*scan_start)(struct ieee80211_scan_state *, 264 struct ieee80211vap *); 265 int (*scan_restart)(struct ieee80211_scan_state *, 266 struct ieee80211vap *); 267 int (*scan_cancel)(struct ieee80211_scan_state *, 268 struct ieee80211vap *); 269 int (*scan_end)(struct ieee80211_scan_state *, 270 struct ieee80211vap *); 271 int (*scan_flush)(struct ieee80211_scan_state *); 272 struct ieee80211_channel *(*scan_pickchan)( 273 struct ieee80211_scan_state *, int); 274 /* add an entry to the cache */ 275 int (*scan_add)(struct ieee80211_scan_state *, 276 const struct ieee80211_scanparams *, 277 const struct ieee80211_frame *, 278 int subtype, int rssi, int noise); 279 /* age and/or purge entries in the cache */ 280 void (*scan_age)(struct ieee80211_scan_state *); 281 /* note that association failed for an entry */ 282 void (*scan_assoc_fail)(struct ieee80211_scan_state *, 283 const uint8_t macaddr[IEEE80211_ADDR_LEN], 284 int reason); 285 /* note that association succeed for an entry */ 286 void (*scan_assoc_success)(struct ieee80211_scan_state *, 287 const uint8_t macaddr[IEEE80211_ADDR_LEN]); 288 /* iterate over entries in the scan cache */ 289 void (*scan_iterate)(struct ieee80211_scan_state *, 290 ieee80211_scan_iter_func *, void *); 291 void (*scan_spare0)(void); 292 void (*scan_spare1)(void); 293 void (*scan_spare2)(void); 294 void (*scan_spare4)(void); 295 }; 296 void ieee80211_scanner_register(enum ieee80211_opmode, 297 const struct ieee80211_scanner *); 298 void ieee80211_scanner_unregister(enum ieee80211_opmode, 299 const struct ieee80211_scanner *); 300 void ieee80211_scanner_unregister_all(const struct ieee80211_scanner *); 301 const struct ieee80211_scanner *ieee80211_scanner_get(enum ieee80211_opmode); 302 #endif /* _NET80211_IEEE80211_SCAN_H_ */ 303