/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$
 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