d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

- Keep recovering from "MFC went wrong". Add missing ieee80211_* parts,

Browse Source 
mergeinfo is already in place
This commit is contained in:
gonzo 2009-10-21 20:33:50 +00:00
parent c4fee3a507
commit 77ad1e2255
7 changed files with 1119 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

194
share/man/man9/ieee80211_amrr.9 Normal file
View File

@ -0,0 +1,194 @@
.\"
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 4, 2009
.Dt IEEE8021_AMRR 9
.Os
.Sh NAME
.Nm ieee80211_amrr
.Nd 802.11 network driver transmit rate control support
.Sh SYNOPSIS
.In net80211/ieee80211_amrr.h
.Ft void
.Fo ieee80211_amrr_init
.Fa "struct ieee80211_amrr *"
.Fa "struct ieee80211vap *"
.Fa "int amin"
.Fa "int amax"
.Fa "int interval"
.Fc
.\"
.Ft void
.Fn ieee80211_amrr_cleanup "struct ieee80211_amrr *"
.\"
.Ft void
.Fn ieee80211_amrr_setinterval "struct ieee80211_amrr *" "int interval"
.\"
.Ft void
.Fo ieee80211_amrr_node_init
.Fa "struct ieee80211_amrr *"
.Fa "struct ieee80211_amrr_node *"
.Fa "struct ieee80211_node *"
.Fc
.\"
.Ft int
.Fo ieee80211_amrr_choose
.Fa "struct ieee80211_node *"
.Fa "struct ieee80211_amrr_node *"
.Fc
.\"
.Ft void
.Fo ieee80211_amrr_tx_complete
.Fa "struct ieee80211_amrr_node *"
.Fa "int ok"
.Fa "int retries"
.Fc
.\"
.Ft void
.Fo ieee80211_amrr_tx_update
.Fa "struct ieee80211_amrr_node *"
.Fa "int txnct"
.Fa "int success"
.Fa "int retrycnt"
.Fc
.Sh DESCRIPTION
.Nm
is an implementation of the AMRR transmit rate control algorithm
for drivers that use the
.Nm net80211
software layer.
A rate control algorithm is responsible for choosing the transmit
rate for each frame.
To maximize throughput algorithms try to use the highest rate that
is appropriate for the operating conditions.
The rate will vary as conditions change; the distance between two stations
may change, transient noise may be present that affects signal quality,
etc.
.Nm
uses very simple information from a driver to do it's job:
whether a frame was successfully delivered and how many transmit
attempts were made.
While this enables its use with virtually any wireless device it
limits it's effectiveness--do not expect it to function well in
difficult environments and/or respond quickly to changing conditions.
.Pp
.Nm
requires per-vap state and per-node state for each station it is to
select rates for.
The API's are designed for drivers to pre-allocate state in the
driver-private extension areas of each vap and node.
For example the
.Xr ral 4
driver defines a vap as:
.Bd -literal -offset indent
struct rt2560_vap {
struct ieee80211vap ral_vap;
struct ieee80211_beacon_offsets ral_bo;
struct ieee80211_amrr amrr;
int (*ral_newstate)(struct ieee80211vap *,
enum ieee80211_state, int);
};
.Ed
.Pp
The
.Vt amrr
structure member holds the per-vap state for
.Nm
and
.Xr ral 4
initializes it in the vap create method with:
.Bd -literal -offset indent
ieee80211_amrr_init(&rvp->amrr, vap,
IEEE80211_AMRR_MIN_SUCCESS_THRESHOLD,
IEEE80211_AMRR_MAX_SUCCESS_THRESHOLD,
500 /* ms */);
.Ed
.Pp
The node is defined as:
.Bd -literal -offset indent
struct rt2560_node {
struct ieee80211_node ni;
struct ieee80211_amrr_node amrr;
};
.Ed
.Pp
with initialization done in the driver's
.Vt iv_newassoc
method:
.Bd -literal -offset indent
static void
rt2560_newassoc(struct ieee80211_node *ni, int isnew)
{
struct ieee80211vap *vap = ni->ni_vap;
ieee80211_amrr_node_init(&RT2560_VAP(vap)->amrr,
&RT2560_NODE(ni)->amrr, ni);
}
.Ed
.Pp
Once
.Nm
state is setup, transmit rates are requested by calling
.Fn ieee80211_amrr_choose
in the transmit path; e.g.:
.Bd -literal -offset indent
tp = &vap->iv_txparms[ieee80211_chan2mode(ni->ni_chan)];
if (IEEE80211_IS_MULTICAST(wh->i_addr1)) {
rate = tp->mcastrate;
} else if (m0->m_flags & M_EAPOL) {
rate = tp->mgmtrate;
} else if (tp->ucastrate != IEEE80211_FIXED_RATE_NONE) {
rate = tp->ucastrate;
} else {
(void) ieee80211_amrr_choose(ni, &RT2560_NODE(ni)->amrr);
rate = ni->ni_txrate;
}
.Ed
.Pp
Note a rate is chosen only for unicast data frames when a fixed
transmit rate is not configured; the other cases are handled with
the
.Nm net80211
transmit parameters.
Note also that
.Fn ieee80211_amrr_choose
writes the chosen rate in
.Vt ni_txrate ;
this eliminates copying the value as it is exported to user applications so
they can display the current transmit rate in status.
.Pp
The remaining work a driver must do is feed status back to
.Nm
when a frame transmit completes using
.Fn ieee80211_amrr_tx_complete .
Drivers that poll a device to retrieve statistics can use
.Fn ieee80211_amrr_tx_update
(instead or in addition).
.Sh SEE ALSO
.Xr ieee80211 9 ,
.Xr ieee80211_output 9

115
share/man/man9/ieee80211_beacon.9 Normal file
View File

@ -0,0 +1,115 @@
.\"
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 4, 2009
.Dt IEEE80211_BEACON 9
.Os
.Sh NAME
.Nm ieee80211_beacon
.Nd 802.11 beacon support
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.Pp
.Ft "struct mbuf *"
.Fo ieee80211_beacon_alloc
.Fa "struct ieee80211_node *"
.Fa "struct ieee80211_beacon_offsets *"
.Fc
.\"
.Ft int
.Fo ieee80211_beacon_update
.Fa "struct ieee80211_node *"
.Fa "struct ieee80211_beacon_offsets *"
.Fa "struct mbuf *"
.Fa "int mcast"
.Fc
.\"
.Ft void
.Fn ieee80211_beacon_notify "struct ieee80211vap *" "int what"
.Sh DESCRIPTION
The
.Nm net80211
software layer provides a support framework for drivers that includes
a template-based mechanism for dynamic update of beacon frames transmit
in hostap, adhoc, and mesh operating modes.
Drivers should use
.Fn ieee80211_beacon_alloc
to create an initial beacon frame.
The
.Vt ieee80211_beacon_offsets
structure holds information about the beacon contents that is used
to optimize updates done with
.Fn ieee80211_beacon_update .
.Pp
Update calls should only be done when something changes that
affects the contents of the beacon frame.
When this happens the
.Dv iv_update_beacon
method is invoked and a driver-supplied routine must do the right thing.
For devices that involve the host to transmit each
beacon frame this work may be as simple as marking a bit in the
.Vt ieee80211_beacon_offsets
structure:
.Bd -literal
static void
ath_beacon_update(struct ieee80211vap *vap, int item)
{
struct ieee80211_beacon_offsets *bo = &ATH_VAP(vap)->av_boff;
setbit(bo->bo_flags, item);
}
.Ed
.Pp
with the
.Fn ieee80211_beacon_update
call done before the next beacon is to be sent.
.Pp
Devices that off-load beacon generation may instead choose to use
this callback to push updates immediately to the device.
Exactly how that is accomplished is unspecified.
One possibility is to update the beacon frame contents and extract
the appropriate information element, but other scenarios are possible.
.Sh MULTI-VAP BEACON SCHEDULING
Drivers that support multiple vaps that can each beacon need to consider
how to schedule beacon frames.
There are two possibilities at the moment:
.Em burst
all beacons at TBTT or
.Em stagger beacons
over the beacon interval.
Bursting beacon frames may result in aperiodic delivery that can affect
power save operation of associated stations.
Applying some jitter (e.g. by randomly ordering burst frames) may be
sufficient to combat this and typically this is not an issue unless
stations are using aggressive power save techniques
such as U-APSD (sometimes employed by VoIP phones).
Staggering frames requires more interrupts and device support that
may not be available.
Staggering beacon frames is usually superior to bursting frames, up to
about eight vaps, at which point the overhead becomes significant and
the channel becomes noticeably busy anyway.
.Sh SEE ALSO
.Xr ieee80211 9

91
share/man/man9/ieee80211_bmiss.9 Normal file
View File

@ -0,0 +1,91 @@
.\"
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 4, 2009
.Dt IEEE80211_BMISS 9
.Os
.Sh NAME
.Nm ieee80211_bmiss
.Nd 802.11 beacon miss support
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.Pp
.Ft void
.Fn ieee80211_beacon_miss "struct ieee80211com *"
.Sh DESCRIPTION
The
.Nm net80211
software layer provides a support framework for drivers that includes
handling beacon miss events in station mode.
Drivers can dispatch beacon miss events that are recognized in hardware or
.Nm net80211
can detect beacon miss if the driver dispatches received beacon frames
through the normal receive path.
Software beacon miss support is especially useful when multiple vaps
are operating and any hardware beacon miss support is not available
(e.g. operating as an access point together with one or more station
mode vaps).
.Pp
Drivers should dispatch beacon miss events recognized in the driver with
.Fn ieee80211_beacon_miss .
This causes some number of ProbeRequest frames to be sent to the
access point to check if the association is still alive.
If no response is received and roaming mode is set to
.Dv IEEE80211_ROAMING_AUTO
then
.Nm net80211
will try to re-associate and if that fails
trigger a scan to look for the access point or another suitable AP.
When the
.Nm net80211
state machine is being operated manually, e.g. by
.Xr wpa_supplicant 8 ,
then applications are notified of the state change and are responsible
for handling the work of scanning for a new access point.
The number of beacon miss events (without a ProbeResponse) is user
settable with the
.Dv IEEE80211_IOC_BMISSTHRESHOLD
request.
.Pp
Software beacon miss detection is enabled per-vap by setting the
.Dv IEEE80211_FEXT_SWBMISS
flag.
Typically this is done when a vap is setup
when the
.Dv IEEE80211_CLONE_NOBEACONS
option is supplied to the clone operation.
But drivers may also force this when they know they need help detecting
beacon miss.
When beacon miss is detected in software the event is dispatched without
driver involvement.
Note that software beacon miss handling is not limited to station mode;
it can be used in any operating mode where beacons from a peer station
are received.
.Sh SEE ALSO
.Xr wpa_supplicant 8 ,
.Xr ieee80211 9 ,
.Xr ieee80211_vap 9

72
share/man/man9/ieee80211_ddb.9 Normal file
View File

@ -0,0 +1,72 @@
.\"
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 4, 2009
.Dt IEEE80211_DDB 9
.Os
.Sh NAME
.Nm ieee80211_ddb
.Nd 802.11 ddb support
.Sh SYNOPSIS
.Bd -ragged
.Cd options DDB
.Ed
.Pp
.Bd -ragged
.Cd show vap [addr]
.Cd show all vaps
.Cd show com [addr]
.Cd show sta [addr]
.Cd show statab [addr]
.Cd show mesh [addr]
.Ed
.Sh DESCRIPTION
The
.Nm net80211
layer includes
.Xr ddb 4
support for displaying important data structures.
This is especially important because wireless applications are often
built for embedded environments where cross-machine or post-mortem
debugging facilities like
.Xr kgdb 1
are infeasible.
.Pp
The most commonly used command is
.Bd -literal -offset indent
show all vaps/a
.Ed
.Pp
which dumps the contents of all
.Vt ieee80211vap ,
.Vt ieee80211com ,
and
.Vt ieee80211_node
data structures in the system.
.Sh SEE ALSO
.Xr ddb 4 ,
.Xr ieee80211 9

143
share/man/man9/ieee80211_regdomain.9 Normal file
View File

@ -0,0 +1,143 @@
.\"
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 4, 2009
.Dt IEEE80211_REGDOMAIN 9
.Os
.Sh NAME
.Nm ieee80211_regdomain
.Nd 802.11 regulatory support
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.In net80211/ieee80211_regdomain.h
.Pp
.Ft int
.Fo ieee80211_init_channels
.Fa "struct ieee80211com *"
.Fa "const struct ieee80211_regdomain *"
.Fa "const uint8_t bands[]"
.Fc
.\"
.Ft void
.Fo ieee80211_sort_channels
.Fa "struct ieee80211_channel *"
.Fa "int nchans"
.Fc
.\"
.Ft "struct ieee80211_appie *"
.Fn ieee80211_alloc_countryie "struct ieee80211com *"
.Sh DESCRIPTION
The
.Nm net80211
software layer provides a support framework for drivers that includes
comprehensive regulatory support.
.Nm net80211
provides mechanisms that enforce
.Em "regulatory policy"
by privileged user applications.
.Pp
Drivers define a device's capabilities and can
intercept and control regulatory changes requested through
.Nm net80211 .
The initial regulatory state, including the channel list, must be
filled in by the driver before calling
.Fn ieee80211_ifattach .
The channel list should reflect the set of channels the device is
.Em calibrated
for use on.
This list may also be requested later through the
.Vt ic_getradiocaps
method in the
.Vt ieee80211com
structure.
The
.Fn ieee80211_init_channels
function is provided as a rudimentary fallback for drivers that do not
(or cannot) fill in a proper channel list.
Default regulatory state is supplied such as the regulatory SKU,
ISO country code, location (e.g. indoor, outdoor), and a set of
frequency bands the device is capable of operating on.
.Nm net80211
populates the channel table in
.Vt ic_channels
with a default set of channels and capabilities.
Note this mechanism should be used with care as any mismatch between
the channel list created and the device's capabilities can result
in runtime errors (e.g. a request to operate on a channel the device
does not support).
The SKU and country information are used for generating 802.11h protocol
elements and related operation such as for 802.11d; mis-setup by a
driver is not fatal, only potentially confusing.
.Pp
Devices that do not have a fixed/default regulatory state can set
the regulatory SKU to
.Dv SKU_DEBUG
and country code to
.Dv CTRY_DEFAULT
and leave proper setup to user applications.
If default settings are known they can be installed and/or an event
can be dispatched to user space using
.Fn ieee80211_notify_country
so that
.Xr devd 8
will do the appropriate setup work at system boot (or device insertion).
.Pp
The channel table is sorted to optimize lookups using the
.Fn ieee80211_sort_channels
routine.
This should be done whenever the channel table contents are modified.
.Pp
The
.Fn ieee80211_alloc_countryie
function allocates an information element as specified by 802.11h.
Because this is expensive to generate it is cached in
.Vt ic_countryie
and generated only when regulatory state changes.
Drivers that call
.Fn ieee80211_alloc_countryie
directly should not help with this caching; doing so may confuse the
.Nm net80211
layer.
.Sh DRIVER REGULATORY CONTROL
Drivers can control regulatory change requests by overriding the
.Vt ic_setregdomain
method that checks change requests.
While drivers can reject any request that does not meet its requirements
it is recommended that one be lenient in what is accepted and, whenever
possible, instead of rejecting a request, alter it to be correct.
For example, if the transmit power cap for a channel is too high the
driver can either reject the request or (better) reduce the cap to be
compliant.
Requests that include unacceptable channels should cause the request
to be rejected as otherwise a mismatch may be created between application
state and the state managed by
.Nm net80211 .
The exact rules by which to operate are still being codified.
.Sh SEE ALSO
.Xr regdomain 5 ,
.Xr ifconfig 8 ,
.Xr ieee80211 9

350
share/man/man9/ieee80211_scan.9 Normal file
View File

@ -0,0 +1,350 @@
.\"
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 4, 2009
.Dt IEEE80211_SCAN 9
.Os
.Sh NAME
.Nm ieee80211_scan
.Nd 802.11 scanning support
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.Pp
.Ft int
.Fo ieee80211_start_scan
.Fa "struct ieee80211vap *"
.Fa "int flags"
.Fa "u_int duration"
.Fa "u_int mindwell"
.Fa "u_int maxdwell"
.Fa "u_int nssid"
.Fa "const struct ieee80211_scan_ssid ssids[]"
.Fc
.\"
.Ft int
.Fo ieee80211_check_scan
.Fa "struct ieee80211vap *"
.Fa "int flags"
.Fa "u_int duration"
.Fa "u_int mindwell"
.Fa "u_int maxdwell"
.Fa "u_int nssid"
.Fa "const struct ieee80211_scan_ssid ssids[]"
.Fc
.\"
.Ft int
.Fn ieee80211_check_scan_current "struct ieee80211vap *"
.\"
.Ft int
.Fn ieee80211_bg_scan "struct ieee80211vap *" "int"
.\"
.Ft int
.Fn ieee80211_cancel_scan "struct ieee80211vap *"
.\"
.Ft int
.Fn ieee80211_cancel_scan_any "struct ieee80211vap *"
.\"
.Ft int
.Fn ieee80211_scan_next "struct ieee80211vap *"
.\"
.Ft int
.Fn ieee80211_scan_done "struct ieee80211vap *"
.\"
.Ft int
.Fn ieee80211_probe_curchan "struct ieee80211vap *" "int"
.\"
.Ft void
.Fo ieee80211_add_scan
.Fa "struct ieee80211vap *"
.Fa "const struct ieee80211_scanparams *"
.Fa "const struct ieee80211_frame *"
.Fa "int subtype"
.Fa "int rssi"
.Fa "int noise"
.Fc
.\"
.Ft void
.Fn ieee80211_scan_timeout "struct ieee80211com *"
.\"
.Ft void
.Fo ieee80211_scan_assoc_fail
.Fa "struct ieee80211vap *"
.Fa "const uint8_t mac[IEEE80211_ADDR_LEN]"
.Fa "int reason"
.Fc
.\"
.Ft void
.Fn ieee80211_scan_flush "struct ieee80211vap *"
.\"
.Ft void
.Fo ieee80211_scan_iterate
.Fa "struct ieee80211vap *"
.Fa "ieee80211_scan_iter_func"
.Fa "void *"
.Fc
.\"
.Ft void
.Fn ieee80211_scan_dump_channels "const struct ieee80211_scan_state *"
.\"
.Ft void
.Fo ieee80211_scanner_register
.Fa "enum ieee80211_opmode"
.Fa "const struct ieee80211_scanner *"
.Fc
.\"
.Ft void
.Fo ieee80211_scanner_unregister
.Fa "enum ieee80211_opmode"
.Fa "const struct ieee80211_scanner *"
.Fc
.\"
.Ft void
.Fn ieee80211_scanner_unregister_all "const struct ieee80211_scanner *"
.\"
.Ft const struct ieee80211_scanner *
.Fn ieee80211_scanner_get "enum ieee80211_opmode"
.Sh DESCRIPTION
The
.Nm net80211
software layer provides an extensible framework for scanning.
Scanning is the procedure by which a station locates a BSS to join
(in infrastructure and IBSS mode), or a channel to use (when operating
as an AP or an IBSS master).
Scans are either
.Dq active
or
.Dq passive .
An active scan causes one or more ProbeRequest frames to be sent on
visiting each channel.
A passive request causes each channel in the scan set to be visited but
no frames to be transmitted; the station only listens for traffic.
Note that active scanning may still need to listen for traffic before
sending ProbeRequest frames depending on regulatory constraints.
.Pp
A scan operation involves constructing a set of channels to inspect
(the scan set),
visiting each channel and collecting information
(e.g. what BSS are present),
and then analyzing the results to make decisions such as which BSS to join.
This process needs to be as fast as possible so
.Nm net80211
does things like intelligently construct scan sets and dwell on a channel
only as long as necessary.
Scan results are cached and the scan cache is used to avoid scanning when
possible and to enable roaming between access points when operating
in infrastructure mode.
.Pp
Scanning is handled by pluggable modules that implement
.Em policy
per-operating mode.
The core scanning support provides an infrastructure to support these
modules and exports a common API to the rest of the
.Nm net80211
layer.
Policy modules decide what channels to visit, what state to record to
make decisions, and selects the final station/channel to return as the
result of a scan.
.Pp
Scanning is done synchronously when initially bringing a vap to
an operational state and optionally in the background to maintain
the scan cache for doing roaming and rogue AP monitoring.
Scanning is not tied to the
.Nm net80211
state machine that governs vaps except for linkage to the
.Dv IEEE80211_S_SCAN
state.
One one vap at a time may be scanning; this scheduling policy
is handle in
.Fn ieee80211_new_state
and is transparent to scanning code.
.Pp
Scanning is controlled by a set of parameters that (potentially)
constrains the channel set and any desired SSID's and BSSID's.
.Nm net80211
comes with a standard scanner module that works with all available
operating modes and supports
.Dq background scanning
and
.Dq roaming
operation.
.Sh SCANNER MODULES
Scanning modules use a registration mechanism to hook into the
.Nm net80211
layer.
Use
.Fn ieee80211_scanner_register
to register a scan module for a particular operating mode and
.Fn ieee80211_scanner_unregister
or
.Fn ieee80211_scanner_unregister_all
to clear entries (typically on module unload).
Only one scanner module can be registered at any time for an operating mode.
.Sh DRIVER SUPPORT
Scanning operations are usually managed by the
.Nm net80211
layer.
Drivers must provide
.Vt ic_scan_start
and
.Vt ic_scan_stop
methods that are called at the start of a scan and when the
work is done; these should handle work such as enabling receive
of Beacon and ProbeResponse frames and disable any BSSID matching.
The
.Vt ic_set_channel
method is used to change channels while scanning.
.Nm net80211
will generate ProbeRequest frames and transmit them using the
.Nm ic_raw_xmit
method.
Frames received while scanning are dispatched to
.Nm net80211
using the normal receive path.
Devices that off-load scan work to firmware most easily mesh with
.Nm net80211
by operating on a channel-at-a-time basis as this defers control to
.Nm net80211's
scan machine scheduler.
But multi-channel scanning
is supported if the driver manually dispatches results using
.Fn ieee80211_add_scan
routine to enter results into the scan cache.
.Sh SCAN REQUESTS
Scan requests occur by way of the
.Dv IEEE80211_SCAN_REQUEST
ioctl or through a change in a vap's state machine that requires
scanning.
In both cases the scan cache can be checked first and, if it is deemed
suitably
.Dq warm
then it's contents are used without leaving the current channel.
To start a scan without checking the cache
.Fn ieee80211_start_scan
can be called; otherwise
.Fn ieee80211_check_scan
can be used to first check the scan cache, kicking off a scan if
the cache contents are out of date.
There is also
.Fn ieee80211_check_scan_current
which is a shorthand for using previously set scan parameters for
checking the scan cache and then scanning.
.Pp
Background scanning is done using
.Fn ieee80211_bg_scan
in a co-routine fashion.
The first call to this routine will start a background scan that
runs for a limited period of time before returning to the BSS channel.
Subsequent calls advance through the scan set until all channels are
visited.
Typically these later calls are timed to allow receipt of
frames buffered by an access point for the station.
.Pp
A scan operation can be canceled using
.Fn ieee80211_cancel_scan
if it was initiated by the specified vap, or
.Fn ieee80211_cancel_scan_any
to force termination regardless which vap started it.
These requests are mostly used by
.Nm net80211
in the transmit path to cancel background scans when frames are to be sent.
Drivers should not need to use these calls (or most of the calls described
on this page).
.Pp
The
.Fn ieee80211_scan_next
and
.Fn ieee80211_scan_done
routines do explicit iteration through the scan set and should
not normally be used by drivers.
.Fn ieee80211_probe_curchan
handles the work of transmitting ProbeRequest frames when visiting
a channel during an active scan.
When the channel attributes are marked with
.Dv IEEE80211_CHAN_PASSIVE
this function will arrange that before any frame is transmitted 802.11
traffic is first received (in order to comply with regulatory constraints).
.Pp
Min/max dwell time parameters are used to constrain time spent visiting
a channel.
The maximum dwell time constrains the time spent listening for traffic.
The minimum dwell time is used to reduce this time--when it is reached
and one or more frames have been received then an immediate channel
change will be done.
Drivers can override this behaviour through the
.Vt iv_scan_mindwell
method.
.Sh SCAN CACHE MANAGEMENT
The scan cache contents are managed by the scan policy module and
are opaque outside this module.
The
.Nm net80211
scan framework defines API's for interacting.
The validity of the scan cache contents are controlled by
.Vt iv_scanvalid
which is exported to user space through the
.Dv IEEE80211_SCAN_VALID
request.
.Pp
The cache contents can be explicitly flushed with
.Fn ieee80211_scan_flush
or by setting the
.Dv IEEE80211_SCAN_FLUSH
flag when starting a scan operation.
.Pp
Scan cache entries are created with the
.Fn ieee80211_add_scan
routine; usually on receipt of Beacon or ProbeResponse frames.
Existing entries are typically updated based on the latest information
though some information such as RSSI and noise floor readings may be
combined to present an average.
.Pp
The cache contents is aged through
.Fn ieee80211_scan_timeout
calls.
Typically these happen together with other station table activity; every
.Dv IEEE80211_INACT_WAIT
seconds (default 15).
.Pp
Individual cache entries are marked usable with
.Fn ieee80211_scan_assoc_success
and faulty with
.Fn ieee80211_scan_assoc_fail
with the latter taking an argument to identify if there was no response
to Authentication/Association requests or if a negative response was
received (which might hasten cache eviction or blacklist the entry).
.Pp
The cache contents can be viewed using the
.Fn ieee80211_scan_iterate
call.
Cache entries are exported in a public format that is exported to user
applications through the
.Dv IEEE80211_SCAN_RESULTS
request.
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr ieee80211 9 .
.Xr ieee80211_proto 9

154
share/man/man9/ieee80211_vap.9 Normal file
View File

@ -0,0 +1,154 @@
.\"
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd August 4, 2009
.Dt IEEE8021_VAP 9
.Os
.Sh NAME
.Nm net80211_vap
.Nd 802.11 network layer virtual radio support
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.Ft int
.Fo ieee80211_vap_setup
.Fa "struct ieee80211com *"
.Fa "struct ieee80211vap *"
.Fa "const char name[IFNAMSIZ]"
.Fa "int unit"
.Fa "int opmode"
.Fa "int flags"
.Fa "const uint8_t bssid[IEEE80211_ADDR_LEN]"
.Fa "const uint8_t macaddr[IEEE80211_ADDR_LEN]"
.Fc
.\"
.Ft int
.Fo ieee80211_vap_attach
.Fa "struct ieee80211vap *"
.Fa "ifm_change_cb_t media_change"
.Fa "ifm_stat_cb_t media_stat"
.Fc
.\"
.Ft void
.Fn ieee80211_vap_detach "struct ieee80211vap *"
.Sh DESCRIPTION
The
.Nm net80211
software layer provides a support framework for drivers that includes
a virtual radio API that is exported to
users through network interfaces (aka vaps) that are cloned from the
underlying device.
These interfaces have an operating mode
(station, adhoc, hostap, wds, monitor, etc.)
that is fixed for the lifetime of the interface.
Devices that can support multiple concurrent interfaces allow
multiple vaps to be cloned.
.Pp
The virtual radio interface defined by the
.Nm net80211
layer means that drivers must be structured to follow specific rules.
Drivers that support only a single interface at any time must still
follow these rules.
.Pp
The virtual radio architecture splits state between a single per-device
.Vt ieee80211com
structure and one or more
.Vt ieee80211vap
structures.
Vaps are created with the
.Dv SIOCIFCREATE2
request.
This results in a call into the driver's
.Vt ic_vap_create
method where the driver can decide if the request should be accepted.
.Pp
The vap creation process is done in three steps.
First the driver allocates the data structure with
.Xr malloc 9 .
This data structure must have an
.Vt ieee80211vap
structure at the front but is usually extended with driver-private state.
Next the vap is setup with a call to
.Fn ieee80211_vap_setup .
This request initializes
.Nm net80211
state but does not activate the interface.
The driver can then override methods setup by
.Nm net80211
and setup driver resources before finally calling
.Fn ieee80211_vap_attach
to complete the process.
Both these calls must be done without holding any driver locks as
work may require the process block/sleep.
.Pp
A vap is deleted when an
.Dv SIOCIFDESTROY
ioctl request is made or when the device detaches (causing all
associated vaps to automatically be deleted).
Delete requests cause the
.Vt ic_vap_delete
method to be called.
Drivers must quiesce the device before calling
.Fn ieee80211_vap_detach
to deactivate the vap and isolate it from activities such as requests
from user applications.
The driver can then reclaim resources held by the vap and re-enable
device operation.
The exact procedure for quiesceing a device is unspecified but typically
it involves blocking interrupts and stopping transmit and receive
processing.
.Sh MULTI-VAP OPERATION
Drivers are responsible for deciding if multiple vaps can be created
and how to manage them.
Whether or not multiple concurrent vaps can be supported depends on a
device's capabilities.
For example, multiple hostap vaps can usually be supported but many
devices do not support assigning each vap a unique BSSID.
If a device supports hostap operation it can usually support concurrent
station mode vaps but possibly with limitations such as losing support
for hardware beacon miss support.
Devices that are capable of hostap operation and can send and receive
4-address frames should be able to support WDS vaps together with an
ap vap.
But in contrast some devices cannot support WDS vaps without at least one
ap vap (this however can be finessed by forcing the ap vap to not transmit
beacon frames).
All devices should support the creation of any number of monitor mode vaps
concurrent with other vaps but it is the responsibility of the driver to
allow this.
.Pp
An important consequence of supporting multiple concurrent vaps is that
a driver's
.Vt iv_newstate
method must be written to handle being called for each vap.
Where necessary, drivers must track private state for all vaps
and not just the one whose state is being changed (e.g. for
handling beacon timers the driver may need to know if all vaps
that beacon are stopped before stopping the hardware timers).
.Sh SEE ALSO
.Xr ieee80211 9 ,
.Xr ifnet 9 ,
.Xr malloc 9