2 .\" Copyright (c) 2009 Sam Leffler, Errno Consulting
3 .\" All rights reserved.
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 AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd 802.11 scanning support
35 .In net80211/ieee80211_var.h
38 .Fo ieee80211_start_scan
39 .Fa "struct ieee80211vap *"
45 .Fa "const struct ieee80211_scan_ssid ssids[]"
49 .Fo ieee80211_check_scan
50 .Fa "struct ieee80211vap *"
56 .Fa "const struct ieee80211_scan_ssid ssids[]"
60 .Fn ieee80211_check_scan_current "struct ieee80211vap *"
63 .Fn ieee80211_bg_scan "struct ieee80211vap *" "int"
66 .Fn ieee80211_cancel_scan "struct ieee80211vap *"
69 .Fn ieee80211_cancel_scan_any "struct ieee80211vap *"
72 .Fn ieee80211_scan_next "struct ieee80211vap *"
75 .Fn ieee80211_scan_done "struct ieee80211vap *"
78 .Fn ieee80211_probe_curchan "struct ieee80211vap *" "int"
81 .Fo ieee80211_add_scan
82 .Fa "struct ieee80211vap *"
83 .Fa "const struct ieee80211_scanparams *"
84 .Fa "const struct ieee80211_frame *"
91 .Fn ieee80211_scan_timeout "struct ieee80211com *"
94 .Fo ieee80211_scan_assoc_fail
95 .Fa "struct ieee80211vap *"
96 .Fa "const uint8_t mac[IEEE80211_ADDR_LEN]"
101 .Fn ieee80211_scan_flush "struct ieee80211vap *"
104 .Fo ieee80211_scan_iterate
105 .Fa "struct ieee80211vap *"
106 .Fa "ieee80211_scan_iter_func"
111 .Fn ieee80211_scan_dump_channels "const struct ieee80211_scan_state *"
114 .Fo ieee80211_scanner_register
115 .Fa "enum ieee80211_opmode"
116 .Fa "const struct ieee80211_scanner *"
120 .Fo ieee80211_scanner_unregister
121 .Fa "enum ieee80211_opmode"
122 .Fa "const struct ieee80211_scanner *"
126 .Fn ieee80211_scanner_unregister_all "const struct ieee80211_scanner *"
128 .Ft const struct ieee80211_scanner *
129 .Fn ieee80211_scanner_get "enum ieee80211_opmode"
133 software layer provides an extensible framework for scanning.
134 Scanning is the procedure by which a station locates a BSS to join
135 (in infrastructure and IBSS mode), or a channel to use (when operating
136 as an AP or an IBSS master).
141 An active scan causes one or more ProbeRequest frames to be sent on
142 visiting each channel.
143 A passive request causes each channel in the scan set to be visited but
144 no frames to be transmitted; the station only listens for traffic.
145 Note that active scanning may still need to listen for traffic before
146 sending ProbeRequest frames depending on regulatory constraints.
148 A scan operation involves constructing a set of channels to inspect
150 visiting each channel and collecting information
151 (e.g. what BSS are present),
152 and then analyzing the results to make decisions such as which BSS to join.
153 This process needs to be as fast as possible so
155 does things like intelligently construct scan sets and dwell on a channel
156 only as long as necessary.
157 Scan results are cached and the scan cache is used to avoid scanning when
158 possible and to enable roaming between access points when operating
159 in infrastructure mode.
161 Scanning is handled by pluggable modules that implement
164 The core scanning support provides an infrastructure to support these
165 modules and exports a common API to the rest of the
168 Policy modules decide what channels to visit, what state to record to
169 make decisions, and selects the final station/channel to return as the
172 Scanning is done synchronously when initially bringing a vap to
173 an operational state and optionally in the background to maintain
174 the scan cache for doing roaming and rogue AP monitoring.
175 Scanning is not tied to the
177 state machine that governs vaps except for linkage to the
180 Only one vap at a time may be scanning; this scheduling policy
182 .Fn ieee80211_new_state
183 and is transparent to scanning code.
185 Scanning is controlled by a set of parameters that (potentially)
186 constrains the channel set and any desired SSID's and BSSID's.
188 comes with a standard scanner module that works with all available
189 operating modes and supports
190 .Dq background scanning
195 Scanning modules use a registration mechanism to hook into the
199 .Fn ieee80211_scanner_register
200 to register a scan module for a particular operating mode and
201 .Fn ieee80211_scanner_unregister
203 .Fn ieee80211_scanner_unregister_all
204 to clear entries (typically on module unload).
205 Only one scanner module can be registered at any time for an operating mode.
207 Scanning operations are usually managed by the
214 methods that are called at the start of a scan and when the
215 work is done; these should handle work such as enabling receive
216 of Beacon and ProbeResponse frames and disable any BSSID matching.
219 method is used to change channels while scanning.
221 will generate ProbeRequest frames and transmit them using the
224 Frames received while scanning are dispatched to
226 using the normal receive path.
227 Devices that off-load scan work to firmware most easily mesh with
229 by operating on a channel-at-a-time basis as this defers control to
231 scan machine scheduler.
232 But multi-channel scanning
233 is supported if the driver manually dispatches results using
234 .Fn ieee80211_add_scan
235 routine to enter results into the scan cache.
237 Scan requests occur by way of the
238 .Dv IEEE80211_SCAN_REQUEST
239 ioctl or through a change in a vap's state machine that requires
241 In both cases the scan cache can be checked first and, if it is deemed
244 then it's contents are used without leaving the current channel.
245 To start a scan without checking the cache
246 .Fn ieee80211_start_scan
247 can be called; otherwise
248 .Fn ieee80211_check_scan
249 can be used to first check the scan cache, kicking off a scan if
250 the cache contents are out of date.
252 .Fn ieee80211_check_scan_current
253 which is a shorthand for using previously set scan parameters for
254 checking the scan cache and then scanning.
256 Background scanning is done using
257 .Fn ieee80211_bg_scan
258 in a co-routine fashion.
259 The first call to this routine will start a background scan that
260 runs for a limited period of time before returning to the BSS channel.
261 Subsequent calls advance through the scan set until all channels are
263 Typically these later calls are timed to allow receipt of
264 frames buffered by an access point for the station.
266 A scan operation can be canceled using
267 .Fn ieee80211_cancel_scan
268 if it was initiated by the specified vap, or
269 .Fn ieee80211_cancel_scan_any
270 to force termination regardless which vap started it.
271 These requests are mostly used by
273 in the transmit path to cancel background scans when frames are to be sent.
274 Drivers should not need to use these calls (or most of the calls described
278 .Fn ieee80211_scan_next
280 .Fn ieee80211_scan_done
281 routines do explicit iteration through the scan set and should
282 not normally be used by drivers.
283 .Fn ieee80211_probe_curchan
284 handles the work of transmitting ProbeRequest frames when visiting
285 a channel during an active scan.
286 When the channel attributes are marked with
287 .Dv IEEE80211_CHAN_PASSIVE
288 this function will arrange that before any frame is transmitted 802.11
289 traffic is first received (in order to comply with regulatory constraints).
291 Min/max dwell time parameters are used to constrain time spent visiting
293 The maximum dwell time constrains the time spent listening for traffic.
294 The minimum dwell time is used to reduce this time--when it is reached
295 and one or more frames have been received then an immediate channel
297 Drivers can override this behaviour through the
300 .Sh SCAN CACHE MANAGEMENT
301 The scan cache contents are managed by the scan policy module and
302 are opaque outside this module.
305 scan framework defines API's for interacting.
306 The validity of the scan cache contents are controlled by
308 which is exported to user space through the
309 .Dv IEEE80211_SCAN_VALID
312 The cache contents can be explicitly flushed with
313 .Fn ieee80211_scan_flush
315 .Dv IEEE80211_SCAN_FLUSH
316 flag when starting a scan operation.
318 Scan cache entries are created with the
319 .Fn ieee80211_add_scan
320 routine; usually on receipt of Beacon or ProbeResponse frames.
321 Existing entries are typically updated based on the latest information
322 though some information such as RSSI and noise floor readings may be
323 combined to present an average.
325 The cache contents is aged through
326 .Fn ieee80211_scan_timeout
328 Typically these happen together with other station table activity; every
329 .Dv IEEE80211_INACT_WAIT
330 seconds (default 15).
332 Individual cache entries are marked usable with
333 .Fn ieee80211_scan_assoc_success
335 .Fn ieee80211_scan_assoc_fail
336 with the latter taking an argument to identify if there was no response
337 to Authentication/Association requests or if a negative response was
338 received (which might hasten cache eviction or blacklist the entry).
340 The cache contents can be viewed using the
341 .Fn ieee80211_scan_iterate
343 Cache entries are exported in a public format that is exported to user
344 applications through the
345 .Dv IEEE80211_SCAN_RESULTS
350 .Xr ieee80211_proto 9