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