2 * Copyright (c) 2005-2009 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.
25 * $FreeBSD: head/sys/net80211/ieee80211_scan.h 195618 2009-07-11 15:02:45Z rpaulo $
28 #ifndef _NET80211_IEEE80211_SCAN_H_
29 #define _NET80211_IEEE80211_SCAN_H_
32 * 802.11 scanning support.
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.
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.
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.
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.
73 #define IEEE80211_SCAN_MAX IEEE80211_CHAN_MAX
75 struct ieee80211_scanner
; /* scan policy state */
77 struct ieee80211_scan_ssid
{
78 int len
; /* length in bytes */
79 uint8_t ssid
[IEEE80211_NWID_LEN
]; /* ssid contents */
81 #define IEEE80211_SCAN_MAX_SSID 1 /* max # ssid's to probe */
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.
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 */
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 */
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.
123 #define IEEE80211_SCAN_FLUSH 0x00010000 /* flush candidate table */
124 #define IEEE80211_SCAN_NOSSID 0x80000000 /* don't update ssid list */
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
*);
132 void ieee80211_scan_dump_channels(const struct ieee80211_scan_state
*);
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);
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
*);
157 void ieee80211_scan_assoc_success(struct ieee80211vap
*,
158 const uint8_t mac
[IEEE80211_ADDR_LEN
]);
160 IEEE80211_SCAN_FAIL_TIMEOUT
= 1, /* no response to mgmt frame */
161 IEEE80211_SCAN_FAIL_STATUS
= 2 /* negative response to " " */
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
*);
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 *);
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 */
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.
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 # */
195 uint16_t fhdwell
; /* FHSS dwell interval */
196 uint16_t capinfo
; /* 802.11 capabilities */
197 uint16_t erp
; /* NB: 0x100 indicates ie present */
200 uint8_t *ies
; /* all captured ies */
201 size_t ies_len
; /* length of all captured ies */
223 * Scan cache entry format used when exporting data from a policy
224 * module; this data may be represented some other way internally.
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
];
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) */
252 MALLOC_DECLARE(M_80211_SCAN
);
255 * Template for an in-kernel scan policy module.
256 * Modules register with the scanning code and are
257 * typically loaded as needed.
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
],
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);
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_ */