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