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