share/man/man9/ieee80211_scan.9

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