1.\" 2.\" Copyright (c) 2009 Sam Leffler, Errno Consulting 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 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. 13.\" 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 24.\" SUCH DAMAGE. 25.\" 26.Dd March 29, 2010 27.Dt IEEE80211_SCAN 9 28.Os 29.Sh NAME 30.Nm ieee80211_scan 31.Nd 802.11 scanning support 32.Sh SYNOPSIS 33.In net80211/ieee80211_var.h 34.Pp 35.Ft int 36.Fo ieee80211_start_scan 37.Fa "struct ieee80211vap *" 38.Fa "int flags" 39.Fa "u_int duration" 40.Fa "u_int mindwell" 41.Fa "u_int maxdwell" 42.Fa "u_int nssid" 43.Fa "const struct ieee80211_scan_ssid ssids[]" 44.Fc 45.\" 46.Ft int 47.Fo ieee80211_check_scan 48.Fa "struct ieee80211vap *" 49.Fa "int flags" 50.Fa "u_int duration" 51.Fa "u_int mindwell" 52.Fa "u_int maxdwell" 53.Fa "u_int nssid" 54.Fa "const struct ieee80211_scan_ssid ssids[]" 55.Fc 56.\" 57.Ft int 58.Fn ieee80211_check_scan_current "struct ieee80211vap *" 59.\" 60.Ft int 61.Fn ieee80211_bg_scan "struct ieee80211vap *" "int" 62.\" 63.Ft int 64.Fn ieee80211_cancel_scan "struct ieee80211vap *" 65.\" 66.Ft int 67.Fn ieee80211_cancel_scan_any "struct ieee80211vap *" 68.\" 69.Ft int 70.Fn ieee80211_scan_next "struct ieee80211vap *" 71.\" 72.Ft int 73.Fn ieee80211_scan_done "struct ieee80211vap *" 74.\" 75.Ft int 76.Fn ieee80211_probe_curchan "struct ieee80211vap *" "int" 77.\" 78.Ft void 79.Fo ieee80211_add_scan 80.Fa "struct ieee80211vap *" 81.Fa "const struct ieee80211_scanparams *" 82.Fa "const struct ieee80211_frame *" 83.Fa "int subtype" 84.Fa "int rssi" 85.Fa "int noise" 86.Fc 87.\" 88.Ft void 89.Fn ieee80211_scan_timeout "struct ieee80211com *" 90.\" 91.Ft void 92.Fo ieee80211_scan_assoc_fail 93.Fa "struct ieee80211vap *" 94.Fa "const uint8_t mac[IEEE80211_ADDR_LEN]" 95.Fa "int reason" 96.Fc 97.\" 98.Ft void 99.Fn ieee80211_scan_flush "struct ieee80211vap *" 100.\" 101.Ft void 102.Fo ieee80211_scan_iterate 103.Fa "struct ieee80211vap *" 104.Fa "ieee80211_scan_iter_func" 105.Fa "void *" 106.Fc 107.\" 108.Ft void 109.Fn ieee80211_scan_dump_channels "const struct ieee80211_scan_state *" 110.\" 111.Ft void 112.Fo ieee80211_scanner_register 113.Fa "enum ieee80211_opmode" 114.Fa "const struct ieee80211_scanner *" 115.Fc 116.\" 117.Ft void 118.Fo ieee80211_scanner_unregister 119.Fa "enum ieee80211_opmode" 120.Fa "const struct ieee80211_scanner *" 121.Fc 122.\" 123.Ft void 124.Fn ieee80211_scanner_unregister_all "const struct ieee80211_scanner *" 125.\" 126.Ft const struct ieee80211_scanner * 127.Fn ieee80211_scanner_get "enum ieee80211_opmode" 128.Sh DESCRIPTION 129The 130.Nm net80211 131software layer provides an extensible framework for scanning. 132Scanning is the procedure by which a station locates a BSS to join 133(in infrastructure and IBSS mode), or a channel to use (when operating 134as an AP or an IBSS master). 135Scans are either 136.Dq active 137or 138.Dq passive . 139An active scan causes one or more ProbeRequest frames to be sent on 140visiting each channel. 141A passive request causes each channel in the scan set to be visited but 142no frames to be transmitted; the station only listens for traffic. 143Note that active scanning may still need to listen for traffic before 144sending ProbeRequest frames depending on regulatory constraints. 145.Pp 146A scan operation involves constructing a set of channels to inspect 147(the scan set), 148visiting each channel and collecting information 149(e.g. what BSS are present), 150and then analyzing the results to make decisions such as which BSS to join. 151This process needs to be as fast as possible so 152.Nm net80211 153does things like intelligently construct scan sets and dwell on a channel 154only as long as necessary. 155Scan results are cached and the scan cache is used to avoid scanning when 156possible and to enable roaming between access points when operating 157in infrastructure mode. 158.Pp 159Scanning is handled by pluggable modules that implement 160.Em policy 161per-operating mode. 162The core scanning support provides an infrastructure to support these 163modules and exports a common API to the rest of the 164.Nm net80211 165layer. 166Policy modules decide what channels to visit, what state to record to 167make decisions, and selects the final station/channel to return as the 168result of a scan. 169.Pp 170Scanning is done synchronously when initially bringing a vap to 171an operational state and optionally in the background to maintain 172the scan cache for doing roaming and rogue AP monitoring. 173Scanning is not tied to the 174.Nm net80211 175state machine that governs vaps except for linkage to the 176.Dv IEEE80211_S_SCAN 177state. 178Only one vap at a time may be scanning; this scheduling policy 179is handled in 180.Fn ieee80211_new_state 181and is transparent to scanning code. 182.Pp 183Scanning is controlled by a set of parameters that (potentially) 184constrains the channel set and any desired SSID's and BSSID's. 185.Nm net80211 186comes with a standard scanner module that works with all available 187operating modes and supports 188.Dq background scanning 189and 190.Dq roaming 191operation. 192.Sh SCANNER MODULES 193Scanning modules use a registration mechanism to hook into the 194.Nm net80211 195layer. 196Use 197.Fn ieee80211_scanner_register 198to register a scan module for a particular operating mode and 199.Fn ieee80211_scanner_unregister 200or 201.Fn ieee80211_scanner_unregister_all 202to clear entries (typically on module unload). 203Only one scanner module can be registered at any time for an operating mode. 204.Sh DRIVER SUPPORT 205Scanning operations are usually managed by the 206.Nm net80211 207layer. 208Drivers must provide 209.Vt ic_scan_start 210and 211.Vt ic_scan_stop 212methods that are called at the start of a scan and when the 213work is done; these should handle work such as enabling receive 214of Beacon and ProbeResponse frames and disable any BSSID matching. 215The 216.Vt ic_set_channel 217method is used to change channels while scanning. 218.Nm net80211 219will generate ProbeRequest frames and transmit them using the 220.Nm ic_raw_xmit 221method. 222Frames received while scanning are dispatched to 223.Nm net80211 224using the normal receive path. 225Devices that off-load scan work to firmware most easily mesh with 226.Nm net80211 227by operating on a channel-at-a-time basis as this defers control to 228.Nm net80211's 229scan machine scheduler. 230But multi-channel scanning 231is supported if the driver manually dispatches results using 232.Fn ieee80211_add_scan 233routine to enter results into the scan cache. 234.Sh SCAN REQUESTS 235Scan requests occur by way of the 236.Dv IEEE80211_SCAN_REQUEST 237ioctl or through a change in a vap's state machine that requires 238scanning. 239In both cases the scan cache can be checked first and, if it is deemed 240suitably 241.Dq warm 242then it's contents are used without leaving the current channel. 243To start a scan without checking the cache 244.Fn ieee80211_start_scan 245can be called; otherwise 246.Fn ieee80211_check_scan 247can be used to first check the scan cache, kicking off a scan if 248the cache contents are out of date. 249There is also 250.Fn ieee80211_check_scan_current 251which is a shorthand for using previously set scan parameters for 252checking the scan cache and then scanning. 253.Pp 254Background scanning is done using 255.Fn ieee80211_bg_scan 256in a co-routine fashion. 257The first call to this routine will start a background scan that 258runs for a limited period of time before returning to the BSS channel. 259Subsequent calls advance through the scan set until all channels are 260visited. 261Typically these later calls are timed to allow receipt of 262frames buffered by an access point for the station. 263.Pp 264A scan operation can be canceled using 265.Fn ieee80211_cancel_scan 266if it was initiated by the specified vap, or 267.Fn ieee80211_cancel_scan_any 268to force termination regardless which vap started it. 269These requests are mostly used by 270.Nm net80211 271in the transmit path to cancel background scans when frames are to be sent. 272Drivers should not need to use these calls (or most of the calls described 273on this page). 274.Pp 275The 276.Fn ieee80211_scan_next 277and 278.Fn ieee80211_scan_done 279routines do explicit iteration through the scan set and should 280not normally be used by drivers. 281.Fn ieee80211_probe_curchan 282handles the work of transmitting ProbeRequest frames when visiting 283a channel during an active scan. 284When the channel attributes are marked with 285.Dv IEEE80211_CHAN_PASSIVE 286this function will arrange that before any frame is transmitted 802.11 287traffic is first received (in order to comply with regulatory constraints). 288.Pp 289Min/max dwell time parameters are used to constrain time spent visiting 290a channel. 291The maximum dwell time constrains the time spent listening for traffic. 292The minimum dwell time is used to reduce this time--when it is reached 293and one or more frames have been received then an immediate channel 294change will be done. 295Drivers can override this behaviour through the 296.Vt iv_scan_mindwell 297method. 298.Sh SCAN CACHE MANAGEMENT 299The scan cache contents are managed by the scan policy module and 300are opaque outside this module. 301The 302.Nm net80211 303scan framework defines API's for interacting. 304The validity of the scan cache contents are controlled by 305.Vt iv_scanvalid 306which is exported to user space through the 307.Dv IEEE80211_SCAN_VALID 308request. 309.Pp 310The cache contents can be explicitly flushed with 311.Fn ieee80211_scan_flush 312or by setting the 313.Dv IEEE80211_SCAN_FLUSH 314flag when starting a scan operation. 315.Pp 316Scan cache entries are created with the 317.Fn ieee80211_add_scan 318routine; usually on receipt of Beacon or ProbeResponse frames. 319Existing entries are typically updated based on the latest information 320though some information such as RSSI and noise floor readings may be 321combined to present an average. 322.Pp 323The cache contents is aged through 324.Fn ieee80211_scan_timeout 325calls. 326Typically these happen together with other station table activity; every 327.Dv IEEE80211_INACT_WAIT 328seconds (default 15). 329.Pp 330Individual cache entries are marked usable with 331.Fn ieee80211_scan_assoc_success 332and faulty with 333.Fn ieee80211_scan_assoc_fail 334with the latter taking an argument to identify if there was no response 335to Authentication/Association requests or if a negative response was 336received (which might hasten cache eviction or blacklist the entry). 337.Pp 338The cache contents can be viewed using the 339.Fn ieee80211_scan_iterate 340call. 341Cache entries are exported in a public format that is exported to user 342applications through the 343.Dv IEEE80211_SCAN_RESULTS 344request. 345.Sh SEE ALSO 346.Xr ioctl 2 , 347.Xr ieee80211 9 , 348.Xr ieee80211_proto 9 349