1170530Ssam/*- 2186904Ssam * Copyright (c) 2005-2009 Sam Leffler, Errno Consulting 3170530Ssam * All rights reserved. 4170530Ssam * 5170530Ssam * Redistribution and use in source and binary forms, with or without 6170530Ssam * modification, are permitted provided that the following conditions 7170530Ssam * are met: 8170530Ssam * 1. Redistributions of source code must retain the above copyright 9170530Ssam * notice, this list of conditions and the following disclaimer. 10170530Ssam * 2. Redistributions in binary form must reproduce the above copyright 11170530Ssam * notice, this list of conditions and the following disclaimer in the 12170530Ssam * documentation and/or other materials provided with the distribution. 13170530Ssam * 14170530Ssam * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 15170530Ssam * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 16170530Ssam * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 17170530Ssam * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 18170530Ssam * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 19170530Ssam * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 20170530Ssam * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 21170530Ssam * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 22170530Ssam * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 23170530Ssam * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24170530Ssam * 25170530Ssam * $FreeBSD$ 26170530Ssam */ 27170530Ssam#ifndef _NET80211_IEEE80211_SCAN_H_ 28170530Ssam#define _NET80211_IEEE80211_SCAN_H_ 29170530Ssam 30178354Ssam/* 31178354Ssam * 802.11 scanning support. 32178354Ssam * 33178354Ssam * Scanning is the procedure by which a station locates a bss to join 34178354Ssam * (infrastructure/ibss mode), or a channel to use (when operating as 35178354Ssam * an ap or ibss master). Scans are either "active" or "passive". An 36178354Ssam * active scan causes one or more probe request frames to be sent on 37178354Ssam * visiting each channel. A passive request causes each channel in the 38178354Ssam * scan set to be visited but no frames to be transmitted; the station 39178354Ssam * only listens for traffic. Note that active scanning may still need 40178354Ssam * to listen for traffic before sending probe request frames depending 41178354Ssam * on regulatory constraints; the 802.11 layer handles this by generating 42178354Ssam * a callback when scanning on a ``passive channel'' when the 43178354Ssam * IEEE80211_FEXT_PROBECHAN flag is set. 44178354Ssam * 45190578Srpaulo * A scan operation involves constructing a set of channels to inspect 46178354Ssam * (the scan set), visiting each channel and collecting information 47178354Ssam * (e.g. what bss are present), and then analyzing the results to make 48178354Ssam * decisions like which bss to join. This process needs to be as fast 49178354Ssam * as possible so we do things like intelligently construct scan sets 50178354Ssam * and dwell on a channel only as long as necessary. The scan code also 51178354Ssam * maintains a cache of recent scan results and uses it to bypass scanning 52178354Ssam * whenever possible. The scan cache is also used to enable roaming 53178354Ssam * between access points when operating in infrastructure mode. 54178354Ssam * 55178354Ssam * Scanning is handled with pluggable modules that implement "policy" 56178354Ssam * per-operating mode. The core scanning support provides an 57178354Ssam * instrastructure to support these modules and exports a common api 58178354Ssam * to the rest of the 802.11 layer. Policy modules decide what 59178354Ssam * channels to visit, what state to record to make decisions (e.g. ap 60178354Ssam * mode scanning for auto channel selection keeps significantly less 61178354Ssam * state than sta mode scanning for an ap to associate to), and selects 62178354Ssam * the final station/channel to return as the result of a scan. 63178354Ssam * 64178354Ssam * Scanning is done synchronously when initially bringing a vap to an 65178354Ssam * operational state and optionally in the background to maintain the 66178354Ssam * scan cache for doing roaming and rogue ap monitoring. Scanning is 67178354Ssam * not tied to the 802.11 state machine that governs vaps though there 68178354Ssam * is linkage to the IEEE80211_SCAN state. Only one vap at a time may 69178354Ssam * be scanning; this scheduling policy is handled in ieee80211_new_state 70178354Ssam * and is invisible to the scanning code. 71178354Ssam*/ 72170530Ssam#define IEEE80211_SCAN_MAX IEEE80211_CHAN_MAX 73170530Ssam 74178354Ssamstruct ieee80211_scanner; /* scan policy state */ 75170530Ssam 76170530Ssamstruct ieee80211_scan_ssid { 77178354Ssam int len; /* length in bytes */ 78178354Ssam uint8_t ssid[IEEE80211_NWID_LEN]; /* ssid contents */ 79170530Ssam}; 80178354Ssam#define IEEE80211_SCAN_MAX_SSID 1 /* max # ssid's to probe */ 81170530Ssam 82178354Ssam/* 83284143Sadrian * High-level implementation visible to ieee80211_scan.[ch]. 84284143Sadrian * 85284143Sadrian * The default scanner (ieee80211_scan_sw.[ch]) implements a software 86284143Sadrian * driven scanner. Firmware driven scanning needs a different set of 87284143Sadrian * behaviours. 88284143Sadrian */ 89284143Sadrianstruct ieee80211_scan_methods { 90284143Sadrian void (*sc_attach)(struct ieee80211com *); 91284143Sadrian void (*sc_detach)(struct ieee80211com *); 92284143Sadrian void (*sc_vattach)(struct ieee80211vap *); 93284143Sadrian void (*sc_vdetach)(struct ieee80211vap *); 94284143Sadrian void (*sc_set_scan_duration)(struct ieee80211vap *, u_int); 95284143Sadrian int (*sc_start_scan)(const struct ieee80211_scanner *, 96284143Sadrian struct ieee80211vap *, int, u_int, u_int, u_int, u_int, 97284143Sadrian const struct ieee80211_scan_ssid ssids[]); 98284143Sadrian int (*sc_check_scan)(const struct ieee80211_scanner *, 99284143Sadrian struct ieee80211vap *, int, u_int, u_int, u_int, u_int, 100284143Sadrian const struct ieee80211_scan_ssid ssids[]); 101284143Sadrian int (*sc_bg_scan)(const struct ieee80211_scanner *, 102284143Sadrian struct ieee80211vap *, int); 103284143Sadrian void (*sc_cancel_scan)(struct ieee80211vap *); 104284143Sadrian void (*sc_cancel_anyscan)(struct ieee80211vap *); 105284143Sadrian void (*sc_scan_next)(struct ieee80211vap *); 106284143Sadrian void (*sc_scan_done)(struct ieee80211vap *); 107284143Sadrian void (*sc_scan_probe_curchan)(struct ieee80211vap *, int); 108284143Sadrian void (*sc_add_scan)(struct ieee80211vap *, 109284143Sadrian struct ieee80211_channel *, 110284143Sadrian const struct ieee80211_scanparams *, 111284143Sadrian const struct ieee80211_frame *, 112284143Sadrian int, int, int); 113284143Sadrian}; 114284143Sadrian 115284143Sadrian/* 116178354Ssam * Scan state visible to the 802.11 layer. Scan parameters and 117178354Ssam * results are stored in this data structure. The ieee80211_scan_state 118178354Ssam * structure is extended with space that is maintained private to 119178354Ssam * the core scanning support. We allocate one instance and link it 120178354Ssam * to the ieee80211com structure; then share it between all associated 121178354Ssam * vaps. We could allocate multiple of these, e.g. to hold multiple 122178354Ssam * scan results, but this is sufficient for current needs. 123178354Ssam */ 124170530Ssamstruct ieee80211_scan_state { 125178354Ssam struct ieee80211vap *ss_vap; 126191746Sthompsa struct ieee80211com *ss_ic; 127170530Ssam const struct ieee80211_scanner *ss_ops; /* policy hookup, see below */ 128170530Ssam void *ss_priv; /* scanner private state */ 129170530Ssam uint16_t ss_flags; 130170530Ssam#define IEEE80211_SCAN_NOPICK 0x0001 /* scan only, no selection */ 131170530Ssam#define IEEE80211_SCAN_ACTIVE 0x0002 /* active scan (probe req) */ 132170530Ssam#define IEEE80211_SCAN_PICK1ST 0x0004 /* ``hey sailor'' mode */ 133170530Ssam#define IEEE80211_SCAN_BGSCAN 0x0008 /* bg scan, exit ps at end */ 134170530Ssam#define IEEE80211_SCAN_ONCE 0x0010 /* do one complete pass */ 135178354Ssam#define IEEE80211_SCAN_NOBCAST 0x0020 /* no broadcast probe req */ 136178354Ssam#define IEEE80211_SCAN_NOJOIN 0x0040 /* no auto-sequencing */ 137170530Ssam#define IEEE80211_SCAN_GOTPICK 0x1000 /* got candidate, can stop */ 138170530Ssam uint8_t ss_nssid; /* # ssid's to probe/match */ 139170530Ssam struct ieee80211_scan_ssid ss_ssid[IEEE80211_SCAN_MAX_SSID]; 140170530Ssam /* ssid's to probe/match */ 141170530Ssam /* ordered channel set */ 142170530Ssam struct ieee80211_channel *ss_chans[IEEE80211_SCAN_MAX]; 143170530Ssam uint16_t ss_next; /* ix of next chan to scan */ 144170530Ssam uint16_t ss_last; /* ix+1 of last chan to scan */ 145170530Ssam unsigned long ss_mindwell; /* min dwell on channel */ 146170530Ssam unsigned long ss_maxdwell; /* max dwell on channel */ 147170530Ssam}; 148170530Ssam 149170530Ssam/* 150170530Ssam * The upper 16 bits of the flags word is used to communicate 151170530Ssam * information to the scanning code that is NOT recorded in 152170530Ssam * ss_flags. It might be better to split this stuff out into 153170530Ssam * a separate variable to avoid confusion. 154170530Ssam */ 155178354Ssam#define IEEE80211_SCAN_FLUSH 0x00010000 /* flush candidate table */ 156178354Ssam#define IEEE80211_SCAN_NOSSID 0x80000000 /* don't update ssid list */ 157170530Ssam 158170530Ssamstruct ieee80211com; 159170530Ssamvoid ieee80211_scan_attach(struct ieee80211com *); 160170530Ssamvoid ieee80211_scan_detach(struct ieee80211com *); 161178354Ssamvoid ieee80211_scan_vattach(struct ieee80211vap *); 162178354Ssamvoid ieee80211_scan_vdetach(struct ieee80211vap *); 163170530Ssam 164170530Ssamvoid ieee80211_scan_dump_channels(const struct ieee80211_scan_state *); 165170530Ssam 166170530Ssam#define IEEE80211_SCAN_FOREVER 0x7fffffff 167178354Ssamint ieee80211_start_scan(struct ieee80211vap *, int flags, 168178354Ssam u_int duration, u_int mindwell, u_int maxdwell, 169170530Ssam u_int nssid, const struct ieee80211_scan_ssid ssids[]); 170178354Ssamint ieee80211_check_scan(struct ieee80211vap *, int flags, 171178354Ssam u_int duration, u_int mindwell, u_int maxdwell, 172170530Ssam u_int nssid, const struct ieee80211_scan_ssid ssids[]); 173178354Ssamint ieee80211_check_scan_current(struct ieee80211vap *); 174178354Ssamint ieee80211_bg_scan(struct ieee80211vap *, int); 175178354Ssamvoid ieee80211_cancel_scan(struct ieee80211vap *); 176178354Ssamvoid ieee80211_cancel_anyscan(struct ieee80211vap *); 177178354Ssamvoid ieee80211_scan_next(struct ieee80211vap *); 178178354Ssamvoid ieee80211_scan_done(struct ieee80211vap *); 179178354Ssamvoid ieee80211_probe_curchan(struct ieee80211vap *, int); 180178354Ssamstruct ieee80211_channel *ieee80211_scan_pickchannel(struct ieee80211com *, int); 181170530Ssam 182170530Ssamstruct ieee80211_scanparams; 183178354Ssamvoid ieee80211_add_scan(struct ieee80211vap *, 184282742Sadrian struct ieee80211_channel *, 185170530Ssam const struct ieee80211_scanparams *, 186170530Ssam const struct ieee80211_frame *, 187192468Ssam int subtype, int rssi, int noise); 188170530Ssamvoid ieee80211_scan_timeout(struct ieee80211com *); 189170530Ssam 190178354Ssamvoid ieee80211_scan_assoc_success(struct ieee80211vap *, 191170530Ssam const uint8_t mac[IEEE80211_ADDR_LEN]); 192170530Ssamenum { 193170530Ssam IEEE80211_SCAN_FAIL_TIMEOUT = 1, /* no response to mgmt frame */ 194170530Ssam IEEE80211_SCAN_FAIL_STATUS = 2 /* negative response to " " */ 195170530Ssam}; 196178354Ssamvoid ieee80211_scan_assoc_fail(struct ieee80211vap *, 197170530Ssam const uint8_t mac[IEEE80211_ADDR_LEN], int reason); 198178354Ssamvoid ieee80211_scan_flush(struct ieee80211vap *); 199170530Ssam 200170530Ssamstruct ieee80211_scan_entry; 201170530Ssamtypedef void ieee80211_scan_iter_func(void *, 202170530Ssam const struct ieee80211_scan_entry *); 203178354Ssamvoid ieee80211_scan_iterate(struct ieee80211vap *, 204170530Ssam ieee80211_scan_iter_func, void *); 205178354Ssamenum { 206178354Ssam IEEE80211_BPARSE_BADIELEN = 0x01, /* ie len past end of frame */ 207178354Ssam IEEE80211_BPARSE_RATES_INVALID = 0x02, /* invalid RATES ie */ 208178354Ssam IEEE80211_BPARSE_XRATES_INVALID = 0x04, /* invalid XRATES ie */ 209178354Ssam IEEE80211_BPARSE_SSID_INVALID = 0x08, /* invalid SSID ie */ 210178354Ssam IEEE80211_BPARSE_CHAN_INVALID = 0x10, /* invalid FH/DSPARMS chan */ 211178354Ssam IEEE80211_BPARSE_OFFCHAN = 0x20, /* DSPARMS chan != curchan */ 212178354Ssam IEEE80211_BPARSE_BINTVAL_INVALID= 0x40, /* invalid beacon interval */ 213193439Ssam IEEE80211_BPARSE_CSA_INVALID = 0x80, /* invalid CSA ie */ 214178354Ssam}; 215170530Ssam 216170530Ssam/* 217170530Ssam * Parameters supplied when adding/updating an entry in a 218170530Ssam * scan cache. Pointer variables should be set to NULL 219170530Ssam * if no data is available. Pointer references can be to 220170530Ssam * local data; any information that is saved will be copied. 221170530Ssam * All multi-byte values must be in host byte order. 222170530Ssam */ 223170530Ssamstruct ieee80211_scanparams { 224178354Ssam uint8_t status; /* bitmask of IEEE80211_BPARSE_* */ 225178354Ssam uint8_t chan; /* channel # from FH/DSPARMS */ 226178354Ssam uint8_t bchan; /* curchan's channel # */ 227178354Ssam uint8_t fhindex; 228178354Ssam uint16_t fhdwell; /* FHSS dwell interval */ 229170530Ssam uint16_t capinfo; /* 802.11 capabilities */ 230178354Ssam uint16_t erp; /* NB: 0x100 indicates ie present */ 231170530Ssam uint16_t bintval; 232170530Ssam uint8_t timoff; 233178354Ssam uint8_t *ies; /* all captured ies */ 234178354Ssam size_t ies_len; /* length of all captured ies */ 235170530Ssam uint8_t *tim; 236170530Ssam uint8_t *tstamp; 237170530Ssam uint8_t *country; 238170530Ssam uint8_t *ssid; 239170530Ssam uint8_t *rates; 240170530Ssam uint8_t *xrates; 241170530Ssam uint8_t *doth; 242170530Ssam uint8_t *wpa; 243170530Ssam uint8_t *rsn; 244170530Ssam uint8_t *wme; 245170530Ssam uint8_t *htcap; 246170530Ssam uint8_t *htinfo; 247170530Ssam uint8_t *ath; 248186904Ssam uint8_t *tdma; 249193439Ssam uint8_t *csa; 250227331Sadrian uint8_t *quiet; 251195618Srpaulo uint8_t *meshid; 252195618Srpaulo uint8_t *meshconf; 253193439Ssam uint8_t *spare[3]; 254170530Ssam}; 255170530Ssam 256170530Ssam/* 257170530Ssam * Scan cache entry format used when exporting data from a policy 258170530Ssam * module; this data may be represented some other way internally. 259170530Ssam */ 260170530Ssamstruct ieee80211_scan_entry { 261170530Ssam uint8_t se_macaddr[IEEE80211_ADDR_LEN]; 262170530Ssam uint8_t se_bssid[IEEE80211_ADDR_LEN]; 263178354Ssam /* XXX can point inside se_ies */ 264170530Ssam uint8_t se_ssid[2+IEEE80211_NWID_LEN]; 265170530Ssam uint8_t se_rates[2+IEEE80211_RATE_MAXSIZE]; 266170530Ssam uint8_t se_xrates[2+IEEE80211_RATE_MAXSIZE]; 267170530Ssam union { 268170530Ssam uint8_t data[8]; 269178354Ssam u_int64_t tsf; 270170530Ssam } se_tstamp; /* from last rcv'd beacon */ 271170530Ssam uint16_t se_intval; /* beacon interval (host byte order) */ 272170530Ssam uint16_t se_capinfo; /* capabilities (host byte order) */ 273170530Ssam struct ieee80211_channel *se_chan;/* channel where sta found */ 274170530Ssam uint16_t se_timoff; /* byte offset to TIM ie */ 275170530Ssam uint16_t se_fhdwell; /* FH only (host byte order) */ 276170530Ssam uint8_t se_fhindex; /* FH only */ 277178354Ssam uint8_t se_dtimperiod; /* DTIM period */ 278178354Ssam uint16_t se_erp; /* ERP from beacon/probe resp */ 279170530Ssam int8_t se_rssi; /* avg'd recv ssi */ 280170530Ssam int8_t se_noise; /* noise floor */ 281178354Ssam uint8_t se_cc[2]; /* captured country code */ 282195618Srpaulo uint8_t se_meshid[2+IEEE80211_MESHID_LEN]; 283178354Ssam struct ieee80211_ies se_ies; /* captured ie's */ 284170530Ssam u_int se_age; /* age of entry (0 on create) */ 285170530Ssam}; 286170530SsamMALLOC_DECLARE(M_80211_SCAN); 287170530Ssam 288170530Ssam/* 289170530Ssam * Template for an in-kernel scan policy module. 290170530Ssam * Modules register with the scanning code and are 291170530Ssam * typically loaded as needed. 292170530Ssam */ 293170530Ssamstruct ieee80211_scanner { 294170530Ssam const char *scan_name; /* printable name */ 295170530Ssam int (*scan_attach)(struct ieee80211_scan_state *); 296170530Ssam int (*scan_detach)(struct ieee80211_scan_state *); 297170530Ssam int (*scan_start)(struct ieee80211_scan_state *, 298178354Ssam struct ieee80211vap *); 299170530Ssam int (*scan_restart)(struct ieee80211_scan_state *, 300178354Ssam struct ieee80211vap *); 301170530Ssam int (*scan_cancel)(struct ieee80211_scan_state *, 302178354Ssam struct ieee80211vap *); 303170530Ssam int (*scan_end)(struct ieee80211_scan_state *, 304178354Ssam struct ieee80211vap *); 305170530Ssam int (*scan_flush)(struct ieee80211_scan_state *); 306178354Ssam struct ieee80211_channel *(*scan_pickchan)( 307178354Ssam struct ieee80211_scan_state *, int); 308170530Ssam /* add an entry to the cache */ 309170530Ssam int (*scan_add)(struct ieee80211_scan_state *, 310282742Sadrian struct ieee80211_channel *, 311170530Ssam const struct ieee80211_scanparams *, 312170530Ssam const struct ieee80211_frame *, 313192468Ssam int subtype, int rssi, int noise); 314170530Ssam /* age and/or purge entries in the cache */ 315170530Ssam void (*scan_age)(struct ieee80211_scan_state *); 316170530Ssam /* note that association failed for an entry */ 317170530Ssam void (*scan_assoc_fail)(struct ieee80211_scan_state *, 318170530Ssam const uint8_t macaddr[IEEE80211_ADDR_LEN], 319170530Ssam int reason); 320170530Ssam /* note that association succeed for an entry */ 321170530Ssam void (*scan_assoc_success)(struct ieee80211_scan_state *, 322170530Ssam const uint8_t macaddr[IEEE80211_ADDR_LEN]); 323170530Ssam /* iterate over entries in the scan cache */ 324170530Ssam void (*scan_iterate)(struct ieee80211_scan_state *, 325170530Ssam ieee80211_scan_iter_func *, void *); 326193239Ssam void (*scan_spare0)(void); 327193239Ssam void (*scan_spare1)(void); 328193239Ssam void (*scan_spare2)(void); 329193239Ssam void (*scan_spare4)(void); 330170530Ssam}; 331170530Ssamvoid ieee80211_scanner_register(enum ieee80211_opmode, 332170530Ssam const struct ieee80211_scanner *); 333170530Ssamvoid ieee80211_scanner_unregister(enum ieee80211_opmode, 334170530Ssam const struct ieee80211_scanner *); 335170530Ssamvoid ieee80211_scanner_unregister_all(const struct ieee80211_scanner *); 336170530Ssamconst struct ieee80211_scanner *ieee80211_scanner_get(enum ieee80211_opmode); 337276730Sadrianvoid ieee80211_scan_update_locked(struct ieee80211vap *vap, 338276730Sadrian const struct ieee80211_scanner *scan); 339276730Sadrianvoid ieee80211_scan_copy_ssid(struct ieee80211vap *vap, 340276730Sadrian struct ieee80211_scan_state *ss, 341276730Sadrian int nssid, const struct ieee80211_scan_ssid ssids[]); 342276730Sadrianvoid ieee80211_scan_dump_probe_beacon(uint8_t subtype, int isnew, 343276730Sadrian const uint8_t mac[IEEE80211_ADDR_LEN], 344276730Sadrian const struct ieee80211_scanparams *sp, int rssi); 345276730Sadrianvoid ieee80211_scan_dump(struct ieee80211_scan_state *ss); 346276730Sadrian 347170530Ssam#endif /* _NET80211_IEEE80211_SCAN_H_ */ 348