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