2 * Copyright (c) 2005-2008 Sam Leffler, Errno Consulting
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
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.
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.
27 #ifndef _NET80211_IEEE80211_SCAN_H_
28 #define _NET80211_IEEE80211_SCAN_H_
31 * 802.11 scanning support.
33 * Scanning is the procedure by which a station locates a bss to join
34 * (infrastructure/ibss mode), or a channel to use (when operating as
35 * an ap or ibss master). Scans are either "active" or "passive". An
36 * active scan causes one or more probe request frames to be sent on
37 * visiting each channel. A passive request causes each channel in the
38 * scan set to be visited but no frames to be transmitted; the station
39 * only listens for traffic. Note that active scanning may still need
40 * to listen for traffic before sending probe request frames depending
41 * on regulatory constraints; the 802.11 layer handles this by generating
42 * a callback when scanning on a ``passive channel'' when the
43 * IEEE80211_FEXT_PROBECHAN flag is set.
45 * A scan operation involves constructing a set of channels to inspec
46 * (the scan set), visiting each channel and collecting information
47 * (e.g. what bss are present), and then analyzing the results to make
48 * decisions like which bss to join. This process needs to be as fast
49 * as possible so we do things like intelligently construct scan sets
50 * and dwell on a channel only as long as necessary. The scan code also
51 * maintains a cache of recent scan results and uses it to bypass scanning
52 * whenever possible. The scan cache is also used to enable roaming
53 * between access points when operating in infrastructure mode.
55 * Scanning is handled with pluggable modules that implement "policy"
56 * per-operating mode. The core scanning support provides an
57 * instrastructure to support these modules and exports a common api
58 * to the rest of the 802.11 layer. Policy modules decide what
59 * channels to visit, what state to record to make decisions (e.g. ap
60 * mode scanning for auto channel selection keeps significantly less
61 * state than sta mode scanning for an ap to associate to), and selects
62 * the final station/channel to return as the result of a scan.
64 * Scanning is done synchronously when initially bringing a vap to an
65 * operational state and optionally in the background to maintain the
66 * scan cache for doing roaming and rogue ap monitoring. Scanning is
67 * not tied to the 802.11 state machine that governs vaps though there
68 * is linkage to the IEEE80211_SCAN state. Only one vap at a time may
69 * be scanning; this scheduling policy is handled in ieee80211_new_state
70 * and is invisible to the scanning code.
72 #define IEEE80211_SCAN_MAX IEEE80211_CHAN_MAX
74 struct ieee80211_scanner; /* scan policy state */
76 struct ieee80211_scan_ssid {
77 int len; /* length in bytes */
78 uint8_t ssid[IEEE80211_NWID_LEN]; /* ssid contents */
80 #define IEEE80211_SCAN_MAX_SSID 1 /* max # ssid's to probe */
83 * Scan state visible to the 802.11 layer. Scan parameters and
84 * results are stored in this data structure. The ieee80211_scan_state
85 * structure is extended with space that is maintained private to
86 * the core scanning support. We allocate one instance and link it
87 * to the ieee80211com structure; then share it between all associated
88 * vaps. We could allocate multiple of these, e.g. to hold multiple
89 * scan results, but this is sufficient for current needs.
91 struct ieee80211_scan_state {
92 struct ieee80211vap *ss_vap;
93 const struct ieee80211_scanner *ss_ops; /* policy hookup, see below */
94 void *ss_priv; /* scanner private state */
96 #define IEEE80211_SCAN_NOPICK 0x0001 /* scan only, no selection */
97 #define IEEE80211_SCAN_ACTIVE 0x0002 /* active scan (probe req) */
98 #define IEEE80211_SCAN_PICK1ST 0x0004 /* ``hey sailor'' mode */
99 #define IEEE80211_SCAN_BGSCAN 0x0008 /* bg scan, exit ps at end */
100 #define IEEE80211_SCAN_ONCE 0x0010 /* do one complete pass */
101 #define IEEE80211_SCAN_NOBCAST 0x0020 /* no broadcast probe req */
102 #define IEEE80211_SCAN_NOJOIN 0x0040 /* no auto-sequencing */
103 #define IEEE80211_SCAN_GOTPICK 0x1000 /* got candidate, can stop */
104 uint8_t ss_nssid; /* # ssid's to probe/match */
105 struct ieee80211_scan_ssid ss_ssid[IEEE80211_SCAN_MAX_SSID];
106 /* ssid's to probe/match */
107 /* ordered channel set */
108 struct ieee80211_channel *ss_chans[IEEE80211_SCAN_MAX];
109 uint16_t ss_next; /* ix of next chan to scan */
110 uint16_t ss_last; /* ix+1 of last chan to scan */
111 unsigned long ss_mindwell; /* min dwell on channel */
112 unsigned long ss_maxdwell; /* max dwell on channel */
116 * The upper 16 bits of the flags word is used to communicate
117 * information to the scanning code that is NOT recorded in
118 * ss_flags. It might be better to split this stuff out into
119 * a separate variable to avoid confusion.
121 #define IEEE80211_SCAN_FLUSH 0x00010000 /* flush candidate table */
122 #define IEEE80211_SCAN_NOSSID 0x80000000 /* don't update ssid list */
125 void ieee80211_scan_attach(struct ieee80211com *);
126 void ieee80211_scan_detach(struct ieee80211com *);
127 void ieee80211_scan_vattach(struct ieee80211vap *);
128 void ieee80211_scan_vdetach(struct ieee80211vap *);
130 void ieee80211_scan_dump_channels(const struct ieee80211_scan_state *);
132 #define IEEE80211_SCAN_FOREVER 0x7fffffff
133 int ieee80211_start_scan(struct ieee80211vap *, int flags,
134 u_int duration, u_int mindwell, u_int maxdwell,
135 u_int nssid, const struct ieee80211_scan_ssid ssids[]);
136 int ieee80211_check_scan(struct ieee80211vap *, int flags,
137 u_int duration, u_int mindwell, u_int maxdwell,
138 u_int nssid, const struct ieee80211_scan_ssid ssids[]);
139 int ieee80211_check_scan_current(struct ieee80211vap *);
140 int ieee80211_bg_scan(struct ieee80211vap *, int);
141 void ieee80211_cancel_scan(struct ieee80211vap *);
142 void ieee80211_cancel_anyscan(struct ieee80211vap *);
143 void ieee80211_scan_next(struct ieee80211vap *);
144 void ieee80211_scan_done(struct ieee80211vap *);
145 void ieee80211_probe_curchan(struct ieee80211vap *, int);
146 struct ieee80211_channel *ieee80211_scan_pickchannel(struct ieee80211com *, int);
148 struct ieee80211_scanparams;
149 void ieee80211_add_scan(struct ieee80211vap *,
150 const struct ieee80211_scanparams *,
151 const struct ieee80211_frame *,
152 int subtype, int rssi, int noise, int rstamp);
153 void ieee80211_scan_timeout(struct ieee80211com *);
155 void ieee80211_scan_assoc_success(struct ieee80211vap *,
156 const uint8_t mac[IEEE80211_ADDR_LEN]);
158 IEEE80211_SCAN_FAIL_TIMEOUT = 1, /* no response to mgmt frame */
159 IEEE80211_SCAN_FAIL_STATUS = 2 /* negative response to " " */
161 void ieee80211_scan_assoc_fail(struct ieee80211vap *,
162 const uint8_t mac[IEEE80211_ADDR_LEN], int reason);
163 void ieee80211_scan_flush(struct ieee80211vap *);
165 struct ieee80211_scan_entry;
166 typedef void ieee80211_scan_iter_func(void *,
167 const struct ieee80211_scan_entry *);
168 void ieee80211_scan_iterate(struct ieee80211vap *,
169 ieee80211_scan_iter_func, void *);
171 IEEE80211_BPARSE_BADIELEN = 0x01, /* ie len past end of frame */
172 IEEE80211_BPARSE_RATES_INVALID = 0x02, /* invalid RATES ie */
173 IEEE80211_BPARSE_XRATES_INVALID = 0x04, /* invalid XRATES ie */
174 IEEE80211_BPARSE_SSID_INVALID = 0x08, /* invalid SSID ie */
175 IEEE80211_BPARSE_CHAN_INVALID = 0x10, /* invalid FH/DSPARMS chan */
176 IEEE80211_BPARSE_OFFCHAN = 0x20, /* DSPARMS chan != curchan */
177 IEEE80211_BPARSE_BINTVAL_INVALID= 0x40, /* invalid beacon interval */
181 * Parameters supplied when adding/updating an entry in a
182 * scan cache. Pointer variables should be set to NULL
183 * if no data is available. Pointer references can be to
184 * local data; any information that is saved will be copied.
185 * All multi-byte values must be in host byte order.
187 struct ieee80211_scanparams {
188 uint8_t status; /* bitmask of IEEE80211_BPARSE_* */
189 uint8_t chan; /* channel # from FH/DSPARMS */
190 uint8_t bchan; /* curchan's channel # */
192 uint16_t fhdwell; /* FHSS dwell interval */
193 uint16_t capinfo; /* 802.11 capabilities */
194 uint16_t erp; /* NB: 0x100 indicates ie present */
197 uint8_t *ies; /* all captured ies */
198 size_t ies_len; /* length of all captured ies */
215 * Scan cache entry format used when exporting data from a policy
216 * module; this data may be represented some other way internally.
218 struct ieee80211_scan_entry {
219 uint8_t se_macaddr[IEEE80211_ADDR_LEN];
220 uint8_t se_bssid[IEEE80211_ADDR_LEN];
221 /* XXX can point inside se_ies */
222 uint8_t se_ssid[2+IEEE80211_NWID_LEN];
223 uint8_t se_rates[2+IEEE80211_RATE_MAXSIZE];
224 uint8_t se_xrates[2+IEEE80211_RATE_MAXSIZE];
225 uint32_t se_rstamp; /* recv timestamp */
229 } se_tstamp; /* from last rcv'd beacon */
230 uint16_t se_intval; /* beacon interval (host byte order) */
231 uint16_t se_capinfo; /* capabilities (host byte order) */
232 struct ieee80211_channel *se_chan;/* channel where sta found */
233 uint16_t se_timoff; /* byte offset to TIM ie */
234 uint16_t se_fhdwell; /* FH only (host byte order) */
235 uint8_t se_fhindex; /* FH only */
236 uint8_t se_dtimperiod; /* DTIM period */
237 uint16_t se_erp; /* ERP from beacon/probe resp */
238 int8_t se_rssi; /* avg'd recv ssi */
239 int8_t se_noise; /* noise floor */
240 uint8_t se_cc[2]; /* captured country code */
241 struct ieee80211_ies se_ies; /* captured ie's */
242 u_int se_age; /* age of entry (0 on create) */
244 MALLOC_DECLARE(M_80211_SCAN);
247 * Template for an in-kernel scan policy module.
248 * Modules register with the scanning code and are
249 * typically loaded as needed.
251 struct ieee80211_scanner {
252 const char *scan_name; /* printable name */
253 int (*scan_attach)(struct ieee80211_scan_state *);
254 int (*scan_detach)(struct ieee80211_scan_state *);
255 int (*scan_start)(struct ieee80211_scan_state *,
256 struct ieee80211vap *);
257 int (*scan_restart)(struct ieee80211_scan_state *,
258 struct ieee80211vap *);
259 int (*scan_cancel)(struct ieee80211_scan_state *,
260 struct ieee80211vap *);
261 int (*scan_end)(struct ieee80211_scan_state *,
262 struct ieee80211vap *);
263 int (*scan_flush)(struct ieee80211_scan_state *);
264 struct ieee80211_channel *(*scan_pickchan)(
265 struct ieee80211_scan_state *, int);
266 /* add an entry to the cache */
267 int (*scan_add)(struct ieee80211_scan_state *,
268 const struct ieee80211_scanparams *,
269 const struct ieee80211_frame *,
270 int subtype, int rssi, int noise, int rstamp);
271 /* age and/or purge entries in the cache */
272 void (*scan_age)(struct ieee80211_scan_state *);
273 /* note that association failed for an entry */
274 void (*scan_assoc_fail)(struct ieee80211_scan_state *,
275 const uint8_t macaddr[IEEE80211_ADDR_LEN],
277 /* note that association succeed for an entry */
278 void (*scan_assoc_success)(struct ieee80211_scan_state *,
279 const uint8_t macaddr[IEEE80211_ADDR_LEN]);
280 /* iterate over entries in the scan cache */
281 void (*scan_iterate)(struct ieee80211_scan_state *,
282 ieee80211_scan_iter_func *, void *);
284 void ieee80211_scanner_register(enum ieee80211_opmode,
285 const struct ieee80211_scanner *);
286 void ieee80211_scanner_unregister(enum ieee80211_opmode,
287 const struct ieee80211_scanner *);
288 void ieee80211_scanner_unregister_all(const struct ieee80211_scanner *);
289 const struct ieee80211_scanner *ieee80211_scanner_get(enum ieee80211_opmode);
290 #endif /* _NET80211_IEEE80211_SCAN_H_ */