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