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