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

MFC 196155:

Browse Source 
First (early) draft of net80211 documentation.  Note this is
    focused on driver writers (as opposed to folks adding to net80211).

Reviewed by:	wkoszek
Approved by:	re (rwatson)
This commit is contained in:
Sam Leffler 2009-08-12 21:06:37 +00:00
parent 747a32aaea
commit 49b62b28b2
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/stable/8/; revision=196157
16 changed files with 2746 additions and 1005 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
share/man/man9/Makefile
View File

@ -121,13 +121,19 @@ MAN= accept_filter.9 \
hashinit.9 \
hexdump.9 \
ieee80211.9 \
ieee80211_amrr.9 \
ieee80211_beacon.9 \
ieee80211_bmiss.9 \
ieee80211_crypto.9 \
ieee80211_ddb.9 \
ieee80211_input.9 \
ieee80211_ioctl.9 \
ieee80211_node.9 \
ieee80211_output.9 \
ieee80211_proto.9 \
ieee80211_radiotap.9 \
ieee80211_regdomain.9 \
ieee80211_scan.9 \
ieee80211_vap.9 \
ifnet.9 \
inittodr.9 \
insmntque.9 \
@ -627,52 +633,62 @@ MLINKS+=hash.9 hash32.9 \
MLINKS+=hashinit.9 hashdestroy.9 \
hashinit.9 hashinit_flags.9 \
hashinit.9 phashinit.9
MLINKS+=ieee80211.9 ieee80211_attach.9 \
ieee80211.9 ieee80211_chan2ieee.9 \
ieee80211.9 ieee80211_chan2mode.9 \
ieee80211.9 ieee80211_ieee2mhz.9 \
ieee80211.9 ieee80211_ifattach.9 \
ieee80211.9 ieee80211_ifdetach.9 \
ieee80211.9 ieee80211_media2rate.9 \
ieee80211.9 ieee80211_media_change.9 \
ieee80211.9 ieee80211_media_init.9 \
ieee80211.9 ieee80211_media_status.9 \
ieee80211.9 ieee80211_mhz2ieee.9 \
ieee80211.9 ieee80211_rate2media.9 \
ieee80211.9 ieee80211_setmode.9 \
ieee80211.9 ieee80211_watchdog.9
MLINKS+=ieee80211_crypto.9 ieee80211_crypto_attach.9 \
ieee80211_crypto.9 ieee80211_crypto_detach.9 \
ieee80211_crypto.9 ieee80211_wep_crypt.9
MLINKS+=ieee80211_input.9 ieee80211_decap.9 \
ieee80211_input.9 ieee80211_recv_mgmt.9
MLINKS+=ieee80211_ioctl.9 ieee80211_cfgget.9 \
ieee80211_ioctl.9 ieee80211_cfgset.9
MLINKS+=ieee80211_node.9 ieee80211_alloc_node.9 \
ieee80211_node.9 ieee80211_begin_scan.9 \
ieee80211_node.9 ieee80211_create_ibss.9 \
ieee80211_node.9 ieee80211_dup_bss.9 \
ieee80211_node.9 ieee80211_end_scan.9 \
ieee80211_node.9 ieee80211_find_node.9 \
ieee80211_node.9 ieee80211_free_allnodes.9 \
MLINKS+=ieee80211.9 ieee80211_ifattach.9 \
ieee80211.9 ieee80211_ifdetach.9
MLINKS+=ieee80211_amrr.9 ieee80211_amrr_init.9 \
ieee80211_amrr.9 ieee80211_amrr_cleanup.9 \
ieee80211_amrr.9 ieee80211_amrr_setinterval.9 \
ieee80211_amrr.9 ieee80211_amrr_node_init.9 \
ieee80211_amrr.9 ieee80211_amrr_tx_complete.9 \
ieee80211_amrr.9 ieee80211_amrr_tx_update.9
MLINKS+=ieee80211_beacon.9 ieee80211_beacon_alloc.9 \
ieee80211_beacon.9 ieee80211_beacon_update.9 \
ieee80211_beacon.9 ieee80211_beacon_notify.9
MLINKS+=ieee80211_bmiss.9 ieee80211_beacon_miss.9
MLINKS+=ieee80211_crypto.9 ieee80211_key_update_begin.9 \
ieee80211_crypto.9 ieee80211_key_update_end.9 \
ieee80211_crypto.9 ieee80211_crypto_newkey.9 \
ieee80211_crypto.9 ieee80211_crypto_setkey.9 \
ieee80211_crypto.9 ieee80211_crypto_delglobalkeys.9 \
ieee80211_crypto.9 ieee80211_crypto_reload_keys.9 \
ieee80211_crypto.9 ieee80211_crypto_decap.9 \
ieee80211_crypto.9 ieee80211_crypto_encap.9 \
ieee80211_crypto.9 ieee80211_crypto_demic.9 \
ieee80211_crypto.9 ieee80211_crypto_enmic.9 \
ieee80211_crypto.9 ieee80211_notify_michael_failure.9 \
ieee80211_crypto.9 ieee80211_notify_replay_failure.9 \
ieee80211_crypto.9 ieee80211_crypto_register.9 \
ieee80211_crypto.9 ieee80211_crypto_unregister.9 \
ieee80211_crypto.9 ieee80211_crypto_available.9
MLINKS+=ieee80211_input.9 ieee80211_input_all.9
MLINKS+=ieee80211_node.9 ieee80211_find_rxnode.9 \
ieee80211_node.9 ieee80211_find_rxnode_withkey.9 \
ieee80211_node.9 ieee80211_ref_node.9 \
ieee80211_node.9 ieee80211_unref_node.9 \
ieee80211_node.9 ieee80211_free_node.9 \
ieee80211_node.9 ieee80211_iterate_nodes.9 \
ieee80211_node.9 ieee80211_lookup_node.9 \
ieee80211_node.9 ieee80211_next_scan.9 \
ieee80211_node.9 ieee80211_node_attach.9 \
ieee80211_node.9 ieee80211_node_detach.9 \
ieee80211_node.9 ieee80211_node_lateattach.9 \
ieee80211_node.9 ieee80211_timeout_nodes.9
MLINKS+=ieee80211_output.9 ieee80211_add_rates.9 \
ieee80211_output.9 ieee80211_add_xrates.9 \
ieee80211_output.9 ieee80211_encap.9 \
ieee80211_output.9 ieee80211_send_mgmt.9
MLINKS+=ieee80211_proto.9 ieee80211_dump_pkt.9 \
ieee80211_proto.9 ieee80211_fix_rate.9 \
ieee80211_proto.9 ieee80211_print_essid.9 \
ieee80211_proto.9 ieee80211_proto_attach.9 \
ieee80211_proto.9 ieee80211_proto_detach.9
MLINKS+=ieee80211_radiotap.9 radiotap.9
ieee80211_node.9 ieee80211_dump_node.9 \
ieee80211_node.9 ieee80211_dump_nodes.9
MLINKS+=ieee80211_output.9 M_WME_GETAC.9 \
ieee80211_output.9 M_SEQNO_GET.9 \
ieee80211_output.9 ieee80211_process_callback.9
MLINKS+=ieee80211_proto.9 ieee80211_new_state.9 \
ieee80211_proto.9 ieee80211_start_all.9 \
ieee80211_proto.9 ieee80211_stop_all.9 \
ieee80211_proto.9 ieee80211_suspend_all.9 \
ieee80211_proto.9 ieee80211_resume_all.9 \
ieee80211_proto.9 ieee80211_waitfor_parent.9
MLINKS+=ieee80211_radiotap.9 radiotap.9 \
ieee80211_radiotap.9 ieee80211_radiotap_attach.9 \
ieee80211_radiotap.9 ieee80211_radiotap_active_vap.9 \
ieee80211_radiotap.9 ieee80211_radiotap_active.9 \
ieee80211_radiotap.9 ieee80211_radiotap_tx.9
MLINKS+=ieee80211_regdomain.9 ieee80211_init_channels.9 \
ieee80211_regdomain.9 ieee80211_sort_channels.9 \
ieee80211_regdomain.9 ieee80211_alloc_countryie.9
MLINKS+=ieee80211_vap.9 ieee80211_vap_setup.9 \
ieee80211_vap.9 ieee80211_vap_attach.9 \
ieee80211_vap.9 ieee80211_vap_detach.9
MLINKS+=ifnet.9 ifaddr.9 \
ifnet.9 if_data.9 \
ifnet.9 ifqueue.9

731
share/man/man9/ieee80211.9
View File

@ -1,6 +1,5 @@
.\"
.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
.\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -25,236 +24,538 @@
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\" $Id: ieee80211.9,v 1.5 2004/03/04 12:33:27 bruce Exp $
.\"
.Dd March 2, 2004
.Dt IEEE80211 9
.Dd August 4, 2009
.Dt NET80211 9
.Os
.Sh NAME
.Nm ieee80211_ifattach , ieee80211_ifdetach ,
.Nm ieee80211_mhz2ieee , ieee80211_chan2ieee , ieee80211_ieee2mhz ,
.Nm ieee80211_media_init , ieee80211_media_change , ieee80211_media_status ,
.Nm ieee80211_watchdog ,
.Nm ieee80211_setmode , ieee80211_chan2mode ,
.Nm ieee80211_rate2media , ieee80211_media2rate
.Nd core 802.11 network stack functions
.Nm net80211
.Nd 802.11 network layer
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.In net80211/ieee80211_proto.h
.Ft void
.Fn ieee80211_ifattach "struct ifnet *ifp"
.Fn ieee80211_ifattach "struct ieee80211com *ic" "const uint8_t macaddr[IEEE80211_ADDR_LEN]"
.Ft void
.Fn ieee80211_ifdetach "struct ifnet *ifp"
.Ft u_int
.Fn ieee80211_mhz2ieee "u_int freq" "u_int flags"
.Ft u_int
.Fn ieee80211_chan2ieee "struct ieee80211com *ic" "struct ieee80211_channel *c"
.Ft u_int
.Fn ieee80211_ieee2mhz "u_int chan" "u_int flags"
.Ft void
.Fo ieee80211_media_init
.Fa "struct ifnet *ifp" "ifm_change_cb_t media_change"
.Fa "ifm_stat_cb_t media_stat"
.Fc
.Fa int
.Fn ieee80211_media_change "struct ifnet *ifp"
.Fa void
.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr"
.Ft void
.Fn ieee80211_watchdog "struct ifnet *ifp"
.Ft int
.Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode"
.Ft enum ieee80211_phymode
.Fo ieee80211_chan2mode
.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
.Fc
.Ft int
.Fo ieee80211_rate2media
.Fa "struct ieee80211com *ic" "int rate" "enum ieee80211_phymode mode"
.Fc
.Ft int
.Fn ieee80211_media2rate "int mword"
.Fn ieee80211_ifdetach "struct ieee80211com *ic"
.Sh DESCRIPTION
The
.Nm ieee80211
collection of functions are used to manage wireless network interfaces in the
system which use the system's software 802.11 network stack.
Most of these functions require that attachment to the stack is performed
before calling.
Several utility functions are also provided; these are safe to call from
any driver without prior initialization.
IEEE 802.11 device drivers are written to use the infrastructure provided
by the
.Nm
software layer.
This software provides a support framework for drivers that includes
ifnet cloning, state management, and a user management API by which
applications interact with 802.11 devices.
Most drivers depend on the
.Nm
layer for protocol services but devices that off-load functionality
may bypass the layer to connect directly to the device
(e.g. the
.Xr ndis 4
emulation support does this).
.Pp
.\"
A
.Nm
device driver implements 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.
This enables construction of interesting applications such as
an AP vap and one or more WDS vaps
or multiple AP vaps, each with a different security model.
The
.Nm
layer virtualizes most 802.11 state
and coordinates vap state changes including scheduling multiple vaps.
State that is not virtualized includes the current channel and
WME/WMM parameters.
Protocol processing is typically handled entirely in the
.Nm
layer with drivers responsible purely for moving data between the host
and device.
Similarly,
.Nm
handles most
.Xr ioctl 2
requests without entering the driver;
instead drivers are notified of state changes that
require their involvement.
.Pp
The virtual radio interface defined by the
.Nm
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.
.Sh DATA STRUCTURES
The virtual radio architecture splits state between a single per-device
.Vt ieee80211com
structure and one or more
.Vt ieee80211vap
structures.
Drivers are expected to setup various shared state in these structures
at device attach and during vap creation but otherwise should treat them
as read-only.
The
.Vt ieee80211com
structure is allocated by the
.Nm
layer as adjunct data to a device's
.Vt ifnet ;
it is accessed through the
.Vt if_l2com
structure member.
The
.Vt ieee80211vap
structure is allocated by the driver in the
.Dq vap create
method
and should be extended with any driver-private state.
This technique of giving the driver control to allocate data structures
is used for other
.Nm
data structures and should be exploited to maintain driver-private state
together with public
.Nm
state.
.Pp
The other main data structures are the station, or node, table
that tracks peers in the local BSS, and the channel table that defines
the current set of available radio channels.
Both tables are bound to the
.Vt ieee80211com
structure and shared by all vaps.
Long-lasting references to a node are counted to guard against
premature reclamation.
In particular every packet sent/received holds a node reference
(either explicitly for transmit or implicitly on receive).
.Pp
The
.Vt ieee80211com
and
.Vt ieee80211vap
structures also hold a collection of method pointers that drivers
fill-in and/or override to take control of certain operations.
These methods are the primary way drivers are bound to the
.Nm
layer and are described below.
.Sh DRIVER ATTACH/DETACH
Drivers attach to the
.Nm
layer with the
.Fn ieee80211_ifattach
function attaches the network interface
.Fa ifp
to the 802.11 network stack layer.
This function must be called before using any of the
.Nm ieee80211
functions which need to store driver state across invocations;
function.
The driver is expected to allocate and setup any device-private
data structures before passing control.
The
.Vt struct ifnet
instance pointed to by
.Fa ifp
MUST be an instance of
.Vt struct ieee80211com ,
with various fields initialized to tell
.Nm ieee80211
about its capabilities.
This function performs Ethernet and BPF attachment (by calling
.Fn ether_ifattach
and
.Fn bpfattach2 )
on behalf of the caller.
It also implements the
.Vt ifmedia
interface.
.Vt ieee80211com
structure must be pre-initialized with state required to setup the
.Nm
layer:
.Bl -tag -width ic_channels
.It Dv ic_ifp
Backpointer to the physical device's ifnet.
.It Dv ic_caps
Device/driver capabilities; see below for a complete description.
.It Dv ic_channels
Table of channels the device is capable of operating on.
This is initially provided by the driver but may be changed
through calls that change the regulatory state.
.It Dv ic_nchan
Number of entries in
.Dv ic_channels .
.El
.Pp
.\"
The
On return from
.Fn ieee80211_ifattach
the driver is expected to override default callback functions in the
.Vt ieee80211com
structure to register it's private routines.
Methods marked with a
.Dq *
must be provided by the driver.
.Bl -tag -width ic_channels
.It Dv ic_vap_create*
Create a vap instance of the specified type (operating mode).
Any fixed BSSID and/or MAC address is provided.
Drivers that support multi-bssid operation may honor the requested BSSID
or assign their own.
.It Dv ic_vap_delete*
Destroy a vap instance created with
.Dv ic_vap_create .
.It Dv ic_getradiocaps
Return the list of calibrated channels for the radio.
The default method returns the current list of channels
(space permitting).
.It Dv ic_setregdomain
Process a request to change regulatory state.
The routine may reject a request or constrain changes (e.g. reduce
transmit power caps).
The default method accepts all proposed changes.
.It Dv ic_send_mgmt
Send an 802.11 management frame.
The default method fabricates the frame using
.Nm
state and passes it to the driver through the
.Dv ic_raw_xmit
method.
.It Dv ic_raw_xmit
Transmit a raw 802.11 frame.
The default method drops the frame and generates a message on the console.
.It Dv ic_updateslot
Update hardware state after an 802.11 IFS slot time change,
There is no default method; the pointer may be NULL in which case
it will not be used.
.It Dv ic_update_mcast
Update hardware for a change in the multicast packet filter,
The default method prints a console message.
.It Dv ic_update_promisc
Update hardware for a change in the promiscuous mode setting.
The default method prints a console message.
.It Dv ic_newassoc
Update driver/device state for association to a new AP (in station mode)
or when a new station associates (e.g. in AP mode).
There is no default method; the pointer may be NULL in which case
it will not be used.
.It Dv ic_node_alloc
Allocate and initialize a
.Vt ieee80211_node
structure.
This method cannot sleep.
The default method allocates zero'd memory using
.Xr malloc 9.
Drivers should override this method to allocate extended storage
for their own needs.
Memory allocated by the driver must be tagged with
.Dv M_80211_NODE
to balance the memory allocation statistics.
.It Dv ic_node_free
Reclaim storage of a node allocated by
.Dv ic_node_alloc .
Drivers are expected to
.Em interpose
their own method to cleanup private state but must call through
this method to allow
.Nm
to reclaim it's private state.
.It Dv ic_node_cleanup
Cleanup state in a
.Vt ieee80211_node
created by
.Dv ic_node_alloc .
This operation is distinguished from
.Dv ic_node_free
in that it may be called long before the node is actually reclaimed
to cleanup adjunct state.
This can happen, for example, when a node must not be reclaimed
due to references held by packets in the transmit queue.
Drivers typically interpose
.Dv ic_node_cleanup
instead of
.Dv ic_node_free .
.It Dv ic_node_age
Age, and potentially reclaim, resources associated with a node.
The default method ages frames on the power-save queue (in AP mode)
and pending frames in the receive reorder queues (for stations using A-MPDU).
.It Dv ic_node_drain
Reclaim all optional resources associated with a node.
This call is used to free up resources when they are in short supply,
.It Dv ic_node_getrssi
Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for
the specified node.
This interface returns a subset of the information
returned by
.Dv ic_node_getsignal ,
The default method calculates a filtered average over the last ten
samples passed in to
.Xr ieee80211_input 9
or
.Xr ieee80211_input_all 9 .
.It Dv ic_node_getsignal
Return the RSSI and noise floor (in .5 dBm units) for a station.
The default method calculates RSSI as described above;
the noise floor returned is the last value supplied to
.Xr ieee80211_input 9
or
.Xr ieee80211_input_all 9 .
.It Dv ic_node_getmimoinfo
Return MIMO radio state for a station in support of the
.Dv IEEE80211_IOC_STA_INFO
ioctl request.
The default method returns nothing.
.It Dv ic_scan_start*
Prepare driver/hardware state for scanning.
This callback is done in a sleepable context.
.It Dv ic_scan_end*
Restore driver/hardware state after scanning completes.
This callback is done in a sleepable context.
.It Dv ic_set_channel*
Set the current radio channel using
.Vt ic_curchan .
This callback is done in a sleepable context.
.It Dv ic_scan_curchan
Start scanning on a channel.
This method is called immediately after each channel change
and must initiate the work to scan a channel and schedule a timer
to advance to the next channel in the scan list.
This callback is done in a sleepable context.
The default method handles active scan work (e.g. sending ProbRequest
frames), and schedules a call to
.Xr ieee80211_scan_next 9
according to the maximum dwell time for the channel.
Drivers that off-load scan work to firmware typically use this method
to trigger per-channel scan activity.
.It Dv ic_scan_mindwell
Handle reaching the minimum dwell time on a channel when scanning.
This event is triggered when one or more stations have been found on
a channel and the minimum dwell time has been reached.
This callback is done in a sleepable context.
The default method signals the scan machinery to advance
to the next channel as soon as possible.
Drivers can use this method to preempt further work (e.g. if scanning
is handled by firmware) or ignore the request to force maximum dwell time
on a channel.
.It Dv ic_recv_action
Process a received Action frame.
The default method points to
.Xr ieee80211_recv_action 9
which provides a mechanism for setting up handlers for each Action frame class.
.It Dv ic_send_action
Transmit an Action frame.
The default method points to
.Xr ieee80211_send_action 9
which provides a mechanism for setting up handlers for each Action frame class.
.It Dv ic_ampdu_enable
Check if transmit A-MPDU should be enabled for the specified station and AC.
The default method checks a per-AC traffic rate against a per-vap
threshold to decide if A-MPDU should be enabled.
This method also rate-limits ADDBA requests so that requests are not
made too frequently when a receiver has limited resources.
.It Dv ic_addba_request
Request A-MPDU transmit aggregation.
The default method sets up local state and issues an
ADDBA Request Action frame.
Drivers may interpose this method if they need to setup private state
for handling transmit A-MPDU.
.It Dv ic_addb_response
Process a received ADDBA Response Action frame and setup resources as
needed for doing transmit A-MPDU,
.It Dv ic_addb_stop
Shutdown an A-MPDU transmit stream for the specified station and AC.
The default method reclaims local state after sending a DelBA Action frame.
.It Dv ic_bar_response
Process a response to a transmitted BAR control frame.
.It Dv ic_ampdu_rx_start
Prepare to receive A-MPDU data from the specified station for the TID.
.It Dv ic_ampdu_rx_stop
Terminate receipt of A-MPDU data from the specified station for the TID.
.El
.Pp
Once the
.Nm
layer is attached to a driver there are two more steps typically done
to complete the work:
.Bl -enum
.It
Setup
.Dq radiotap support
for capturing raw 802.11 packets that pass through the device.
This is done with a call to
.Xr ieee80211_radiotap_attach 9 .
.It
Do any final device setup like enabling interrupts.
.El
.Pp
State is torn down and reclaimed with a call to
.Fn ieee80211_ifdetach .
Note this call may result in multiple callbacks into the driver
so it should be done before any critical driver state is reclaimed.
On return from
.Fn ieee80211_ifdetach
function frees any
.Nm ieee80211
structures associated with the driver, and performs Ethernet and BPF
detachment on behalf of the caller.
.Pp
.\"
all associated vaps and ifnet structures are reclaimed or inaccessible
to user applications so it is safe to teardown driver state without
worry about being re-entered.
The driver is responsible for calling
.Xr if_free 9
on the ifnet it allocated for the physical device.
.Sh DRIVER CAPABILITIES
Driver/device capabilities are specified using several sets of flags
in the
.Vt ieee80211com
structure.
General capabilities are specified by
.Vt ic_caps .
Hardware cryptographic capabilities are specified by
.Vt ic_cryptocaps .
802.11n capabilities, if any, are specified by
.Vt ic_htcaps .
The
.Fn ieee80211_mhz2ieee
utility function converts the frequency
.Fa freq
(specified in MHz) to an IEEE 802.11 channel number.
The
.Fa flags
argument is a hint which specifies whether the frequency is in
the 2GHz ISM band
.Pq Vt IEEE80211_CHAN_2GHZ
or the 5GHz band
.Pq Vt IEEE80211_CHAN_5GHZ ;
appropriate clipping of the result is then performed.
.Pp
.\"
The
.Fn ieee80211_chan2ieee
function converts the channel specified in
.Fa *c
to an IEEE channel number for the driver
.Fa ic .
If the conversion would be invalid, an error message is printed to the
system console.
This function REQUIRES that the driver is hooked up to the
.Nm ieee80211
subsystem.
.Pp
.\"
The
.Fn ieee80211_ieee2mhz
utility function converts the IEEE channel number
.Ft chan
to a frequency (in MHz).
The
.Fa flags
argument is a hint which specifies whether the frequency is in
the 2GHz ISM band
.Pq Vt IEEE80211_CHAN_2GHZ
or the 5GHz band
.Pq Vt IEEE80211_CHAN_5GHZ ;
appropriate clipping of the result is then performed.
.Pp
.\"
The
.Fn ieee80211_media_init
function initializes media data structures used by the
.Vt ifmedia
interface, for the driver
.Fa ifp .
It must be called by the driver after calling
.Fn ieee80211_attach
and before calling most
.Nm ieee80211
functions.
The
.Fa media_change
.Nm
layer propagates a subset of these capabilities to each vap through
the equivalent fields:
.Vt iv_caps ,
.Vt iv_cryptocaps ,
and
.Fa media_stat
arguments specify helper functions which will be invoked by the
.Vt ifmedia
framework when the user changes or queries media options,
using a command such as
.Xr ifconfig 8 .
.Vt iv_htcaps .
The following general capabilities are defined:
.Bl -tag -width IEEE80211_C_8023ENCAP
.It Dv IEEE80211_C_STA
Device is capable of operating in station (aka Infrastructure) mode.
.It Dv IEEE80211_C_8023ENCAP
Device requires 802.3-encapsulated frames be passed for transmit.
By default
.Nm
will encapsulate all outbound frames as 802.11 frames (without a PLCP header).
.It Dv IEEE80211_C_FF
Device supports Atheros Fast-Frames.
.It Dv IEEE80211_C_TURBOP
Device supports Atheros Dynamic Turbo mode.
.It Dv IEEE80211_C_IBSS
Device is capable of operating in adhoc/IBSS mode.
.It Dv IEEE80211_C_PMGT
Device supports dynamic power-management (aka power save) in station mode.
.It Dv IEEE80211_C_HOSTAP
Device is capable of operating as an Access Point in Infrastructure mode.
.It Dv IEEE80211_C_AHDEMO
Device is capable of operating in Adhoc Demo mode.
In this mode the device is used purely to send/receive raw 802.11 frames.
.It Dv IEEE80211_C_SWRETRY
Device supports software retry of transmitted frames.
.It Dv IEEE80211_C_TXPMGT
Device support dynamic transmit power changes on transmitted frames;
also known as Transmit Power Control (TPC).
.It Dv IEEE80211_C_SHSLOT
Device supports short slot time operation (for 802.11g).
.It Dv IEEE80211_C_SHPREAMBLE
Device supports short preamble operation (for 802.11g).
.It Dv IEEE80211_C_MONITOR
Device is capable of operating in monitor mode.
.It Dv IEEE80211_C_DFS
Device supports radar detection and/or DFS.
DFS protocol support can be handled by
.Nm
but the device must be capable of detecting radar events.
.It Dv IEEE80211_C_MBSS
Device is capable of operating in MeshBSS (MBSS) mode
(as defined by 802.11s Draft 3.0).
.It Dv IEEE80211_C_WPA1
Device supports WPA1 operation.
.It Dv IEEE80211_C_WPA2
Device supports WPA2/802.11i operation.
.It Dv IEEE80211_C_BURST
Device supports frame bursting.
.It Dv IEEE80211_C_WME
Device supports WME/WMM operation
(at the moment this is mostly support for sending and receiving
QoS frames with EDCF).
.It Dv IEEE80211_C_WDS
Device supports transmit/receive of 4-address frames.
.It Dv IEEE80211_C_BGSCAN
Device supports background scanning.
.It Dv IEEE80211_C_TXFRAG
Device supports transmit of fragmented 802.11 frames.
.It Dv IEEE80211_C_TDMA
Device is capable of operating in TDMA mode.
.El
.Pp
.\"
The
.Fn ieee80211_media_status
and
.Fn ieee80211_media_change
functions are device-independent handlers for
.Vt ifmedia
commands and are not intended to be called directly.
The follow general crypto capabilities are defined.
In general
.Nm
will fall-back to software support when a device is not capable
of hardware acceleration of a cipher.
This can be done on a per-key basis.
.Nm
can also handle software
.Dv Michael
calculation combined with hardware
.Dv AES
acceleration.
.Bl -tag -width IEEE80211_C_8023ENCAP
.It Dv IEEE80211_CRYPTO_WEP
Device supports hardware WEP cipher.
.It Dv IEEE80211_CRYPTO_TKIP
Device supports hardware TKIP cipher.
.It Dv IEEE80211_CRYPTO_AES_OCB
Device supports hardware AES-OCB cipher.
.It Dv IEEE80211_CRYPTO_AES_CCM
Device supports hardware AES-CCM cipher.
.It Dv IEEE80211_CRYPTO_TKIPMIC
Device supports hardware Michael for use with TKIP.
.It Dv IEEE80211_CRYPTO_CKIP
Devices supports hardware CKIP cipher.
.El
.Pp
.\"
The
.Fn ieee80211_watchdog
function is intended to be called from a driver's
.Va if_watchdog
routine.
It is used to perform periodic cleanup of state within the software 802.11
stack, as well as timing out scans.
.Pp
.\"
The
.Fn ieee80211_setmode
function is called from within the 802.11 stack to change the mode
of the driver's PHY; it is not intended to be called directly.
.Pp
.\"
The
.Fn ieee80211_chan2mode
function returns the PHY mode required for use with the channel
.Fa chan
on the device
.Fa ic .
This is typically used when selecting a rate set, to be advertised in
beacons, for example.
.Pp
.\"
The
.Fn ieee80211_rate2media
function converts the bit rate
.Fa rate
(measured in units of 0.5Mbps) to an
.Vt ifmedia
sub-type, for the device
.Fa ic
running in PHY mode
.Fa mode .
The
.Fn ieee80211_media2rate
performs the reverse of this conversion, returning the bit rate (in 0.5Mbps
units) corresponding to an
.Vt ifmedia
sub-type.
.\"
The follow general 802.11n capabilities are defined.
The first capabilities are defined exactly as they appear in the
802.11n specification.
Capabilities beginning with IEEE80211_HTC_AMPDU are used soley by the
.Nm
layer.
.Bl -tag -width IEEE80211_C_8023ENCAP
.It Dv IEEE80211_HTCAP_CHWIDTH40
Device supports 20/40 channel width operation.
.It Dv IEEE80211_HTCAP_SMPS_DYNAMIC
Device supports dynamic SM power save operation.
.It Dv IEEE80211_HTCAP_SMPS_ENA
Device supports static SM power save operation.
.It Dv IEEE80211_HTCAP_GREENFIELD
Device supports Greenfield preamble.
.It Dv IEEE80211_HTCAP_SHORTGI20
Device supports Short Guard Interval on 20MHz channels.
.It Dv IEEE80211_HTCAP_SHORTGI40
Device supports Short Guard Interval on 40MHz channels.
.It Dv IEEE80211_HTCAP_TXSTBC
Device supports Space Time Block Convolution (STBC) for transmit.
.It Dv IEEE80211_HTCAP_RXSTBC_1STREAM
Device supports 1 spatial stream for STBC receive.
.It Dv IEEE80211_HTCAP_RXSTBC_2STREAM
Device supports 1-2 spatial streams for STBC receive.
.It Dv IEEE80211_HTCAP_RXSTBC_3STREAM
Device supports 1-3 spatial streams for STBC receive.
.It Dv IEEE80211_HTCAP_MAXAMSDU_7935
Device supports A-MSDU frames up to 7935 octets.
.It Dv IEEE80211_HTCAP_MAXAMSDU_3839
Device supports A-MSDU frames up to 3839 octets.
.It Dv IEEE80211_HTCAP_DSSSCCK40
Device supports use of DSSS/CCK on 40MHz channels.
.It Dv IEEE80211_HTCAP_PSMP
Device supports PSMP.
.It Dv IEEE80211_HTCAP_40INTOLERANT
Device is intolerant of 40MHz wide channel use.
.It Dv IEEE80211_HTCAP_LSIGTXOPPROT
Device supports L-SIG TXOP protection.
.It Dv IEEE80211_HTC_AMPDU
Device supports A-MPDU aggregation.
Note that any 802.11n compliant device must support A-MPDU receive
so this implicitly means support for
.Em transmit
of A-MPDU frames.
.It Dv IEEE80211_HTC_AMSDU
Device supports A-MSDU aggregation.
Note that any 802.11n compliant device must support A-MSDU receive
so this implicitly means support for
.Em transmit
of A-MSDU frames.
.It Dv IEEE80211_HTC_HT
Device supports High Throughput (HT) operation.
This capability must be set to enable 802.11n functionality
in
.Nm .
.It Dv IEEE80211_HTC_SMPS
Device supports MIMO Power Save operation.
.It Dv IEEE80211_HTC_RIFS
Device supports Reduced Inter Frame Spacing (RIFS).
.El
.Sh SEE ALSO
.Xr ieee80211_crypto 9 ,
.Xr ioctl 2 ,
.Xr ndis 4 ,
.Xr ieee80211_input 9 ,
.Xr ieee80211_ioctl 9 ,
.Xr ieee80211_node 9 ,
.Xr ieee80211_output 9 ,
.Xr ieee80211_proto 9 ,
.Xr ieee80211_radiotap 9 ,
.Xr ifnet 9
.Sh HISTORY
The
.Nm ieee80211
series of functions first appeared in
.Nx 1.5 ,
and were later ported to
.Fx 4.6 .
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
and
.An Darron Broad Aq darron@kewl.org .
.Xr ieee80211_input_all 9 ,
.Xr ieee80211_scan_next 9 ,
.Xr ieee80211_recv_action 9 ,
.Xr ieee80211_send_action 9 ,
.Xr ieee80211_radiotap_attach 9 ,
.Xr ifnet 9 ,
.Xr malloc 9 .

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 ieee80211 9 ,
.Xr ieee80211_vap 9 ,
.Xr wpa_supplicant 8 ,

277
share/man/man9/ieee80211_crypto.9
View File

@ -27,76 +27,233 @@
.\" $FreeBSD$
.\" $Id: ieee80211_crypto.9,v 1.3 2004/03/04 10:42:56 bruce Exp $
.\"
.Dd March 2, 2004
.Dd August 4, 2009
.Dt IEEE80211_CRYPTO 9
.Os
.Sh NAME
.Nm ieee80211_crypto_attach , ieee80211_crypto_detach , ieee80211_wep_crypt
.Nd 802.11 WEP encryption functions
.Nm ieee80211_crypto
.Nd 802.11 cryptographic support
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.\"
.Pp
.Ft void
.Fn ieee80211_crypto_attach "struct ifnet *ifp"
.Fn ieee80211_crypto_register "const struct ieee80211_cipher *"
.\"
.Ft void
.Fn ieee80211_crypto_detach "struct ifnet *ifp"
.Ft struct mbuf *
.Fn ieee80211_wep_crypt "struct ifnet *ifp" "struct mbuf *m0" "int txflag"
.Fn ieee80211_crypto_unregister "const struct ieee80211_cipher *"
.\"
.Ft int
.Fn ieee80211_crypto_available "int cipher"
.\"
.Pp
.Ft void
.Fo ieee80211_notify_replay_failure
.Fa "struct ieee80211vap *"
.Fa "const struct ieee80211_frame *"
.Fa "const struct ieee80211_key *"
.Fa "uint64_t rsc"
.Fa "int tid"
.Fc
.\"
.Ft void
.Fo ieee80211_notify_michael_failure
.Fa "struct ieee80211vap *"
.Fa "const struct ieee80211_frame *"
.Fa "u_int keyix"
.Fc
.\"
.Ft int
.Fo ieee80211_crypto_newkey
.Fa "struct ieee80211vap *
.Fa "int cipher
.Fa "int flags
.Fa "struct ieee80211_key *
.Fc
.\"
.Ft int
.Fn ieee80211_crypto_setkey "struct ieee80211vap *" "struct ieee80211_key *"
.\"
.Ft int
.Fn ieee80211_crypto_delkey "struct ieee80211vap *" "struct ieee80211_key *"
.\"
.Ft void
.Fn ieee80211_key_update_begin "struct ieee80211vap *"
.\"
.Ft void
.Fn ieee80211_key_update_end "struct ieee80211vap *"
.\"
.Ft void
.Fn ieee80211_crypto_delglobalkeys "struct ieee80211vap *"
.\"
.Ft void
.Fn ieee80211_crypto_reload_keys "struct ieee80211com *"
.\"
.Pp
.Ft struct ieee80211_key *
.Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *"
.\"
.Ft struct ieee80211_key *
.Fn ieee80211_crypto_decap "struct ieee80211_node *" "struct mbuf *" "int flags"
.\"
.Ft int
.Fo ieee80211_crypto_demic
.Fa "struct ieee80211vap *"
.Fa "struct ieee80211_key *"
.Fa "struct mbuf *"
.Fa "int force"
.Fc
.\"
.Ft int
.Fo ieee80211_crypto_enmic
.Fa "struct ieee80211vap *"
.Fa "struct ieee80211_key *"
.Fa "struct mbuf *"
.Fa "int force"
.Fc
.Sh DESCRIPTION
These functions provide software encryption support
for 802.11 device drivers.
The
.Nm net80211
layer includes comprehensive cryptographic support for 802.11 protocols.
Software implementations of ciphers required by
WPA and 802.11i are provided as well as encap/decap processing of 802.11 frames.
Software ciphers are written as kernel modules and
register with the core crypto support.
The cryptographic framework supports hardware acceleration of ciphers
by drivers with automatic fall-back to software implementations when a
driver is unable to provide necessary hardware services.
.Sh CRYPTO CIPHER MODULES
.Nm net80211
cipher modules register their services using
.Fn ieee80211_crypto_register
and supply a template that describes their operation.
This
.Vt ieee80211_cipher
structure defines protocol-related state such as the number of bytes
of space in the 802.11 header to reserve/remove during encap/decap
and entry points for setting up keys and doing cryptographic operations.
.Pp
.\"
The
.Fn ieee80211_crypto_attach
function initializes crypto support for the interface
.Fa ifp ,
and sets the initialization vector (IV) for WEP encryption to
a random number derived from a secure PRNG.
Cipher modules can associate private state to each key through the
.Vt wk_private
structure member.
If state is setup by the module it will be called before a key is destroyed
so it can reclaim resources.
.Pp
.\"
Crypto modules can notify the system of two events.
When a packet replay event is recognized
.Fn ieee80111_notify_replay_failure
can be used to signal the event.
When a
.Dv TKIP
Michael failure is detected
.Fn ieee80211_notify_michael_failure
can be invoked.
Drivers may also use these routines to signal events detected by the
hardware.
.Sh CRYPTO KEY MANAGEMENT
The
.Fn ieee80211_crypto_detach
function frees data structures associated with crypto support
for the interface
.Fa ifp .
.Nm net80211
layer implements a per-vap 4-element
.Dq global key table
and a per-station
.Dq unicast key
for protocols such as WPA, 802.1x, and 802.11i.
The global key table is designed to support legacy WEP operation
and Multicast/Group keys,
though some applications also use it to implement WPA in station mode.
Keys in the global table are identified by a key index in the range 0-3.
Per-station keys are identified by the MAC address of the station and
are typically used for unicast PTK bindings.
.Pp
.\"
.Nm net80211
provides
.Xr ioctl 2
operations for managing both global and per-station keys.
Drivers typically do not participate in software key management;
they are involved only when providing hardware acceleration of
cryptographic operations.
.Pp
.Fn ieee80211_crypto_newkey
is used to allocate a new
.Nm net80211
key or reconfigure an existing key.
The cipher must be specified along with any fixed key index.
The
.Fn ieee80211_wep_crypt
function runs the appropriate WEP encryption algorithm over the 802.11
encapsulated frame held in the mbuf chain
.Fa m0 ,
for transmission or reception on the interface
.Fa ifp .
The
.Fa txflag
argument specifies whether the frame is being received or transmitted.
A value of 0 indicates that the frame is being received and should
therefore be decrypted; a non-zero value indicates that the frame
is being transmitted
and should be encrypted.
.\"
.Sh IMPLEMENTATION NOTES
The
.Fn ieee80211_wep_crypt
function stores its IV in the interface's embedded
.Vt struct ieee80211com
instance.
.Sh SEE ALSO
.Xr awi 4 ,
.Xr wi 4 ,
.Xr arc4random 9 ,
.Xr ieee80211 9 ,
.Xr ifnet 9
.Sh HISTORY
The
.Nm ieee80211
series of functions first appeared in
.Nx 1.5 ,
and were later ported to
.Fx 4.6 .
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
.Nm net80211
layer will handle allocating cipher and driver resources to support the key.
.Pp
Once a key is allocated it's contents can be set using
.Fn ieee80211_crypto_setkey
and deleted with
.Fn ieee80211_crypto_delkey
(with any cipher and driver resources reclaimed).
.Pp
.Fn ieee80211_crypto_delglobalkeys
is used to reclaim all keys in the global key table for a vap; it
typically is used only within the
.Nm net80211
layer.
.Pp
.Fn ieee80211_crypto_reload_keys
handles hardware key state reloading from software key state, such
as required after a suspend/resume cycle.
.Sh DRIVER CRYPTO SUPPORT
Drivers identify ciphers they have hardware support for through the
.Vt ic_cryptocaps
field of the
.Vt ieee80211com
structure.
If hardware support is available then a driver should also fill in the
.Dv iv_key_alloc ,
.Dv iv_key_set ,
and
.An Darron Broad Aq darron@kewl.org .
.Dv iv_key_delete
methods of each
.Vt ieee80211vap
created for use with the device.
In addition the methods
.Dv iv_key_update_begin
and
.Dv iv_key_update_end
can be setup to handle synchronization requirements
for updating hardware key state.
.Pp
When
.Nm net80211
allocates a software key and the driver can accelerate the
cipher operations the
.Dv iv_key_alloc
method will be invoked.
Drivers may return a token that is associated with outbound traffic
(for use in encrypting frames).
Otherwise, e.g. if hardware resources are not available, the driver will
not return a token and
.Nm net80211
will arrange to do the work in software and pass frames
to the driver that are already prepared for transmission.
.Pp
For receive, drivers mark frames with the
.Dv M_WEP
mbuf flag to indicate the hardware has decrypted the payload.
If frames have the
.Dv IEEE80211_FC1_WEP
bit marked in their 802.11 header and are not tagged with
.Dv M_WEP
then decryption is done in software.
For more complicated scenarios the software key state is consulted; e.g.
to decide if Michael verification needs to be done in software after
the hardware has handled TKIP decryption.
.Pp
Drivers that manage complicated key data structures, e.g. faulting
software keys into a hardware key cache, can safely manipulate software
key state by bracketing their work with calls to
.Fn ieee80211_key_update_begin
and
.Fn ieee80211_key_update_end .
These calls also synchronize hardware key state update
when receive traffic is active.
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr wlan_ccmp 4 ,
.Xr wlan_tkip 4 ,
.Xr wlan_wep 4 .

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
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 .

135
share/man/man9/ieee80211_input.9
View File

@ -25,89 +25,92 @@
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\" $Id: ieee80211_input.9,v 1.6 2004/03/04 12:33:27 bruce Exp $
.\"
.Dd March 2, 2004
.Dd August 4, 2009
.Dt IEEE80211_INPUT 9
.Os
.Sh NAME
.Nm ieee80211_input , ieee80211_decap , ieee80211_recv_mgmt
.Nm ieee80211_input
.Nd software 802.11 stack input functions
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.In net80211/ieee80211_proto.h
.Ft void
.Fo ieee80211_input
.Fa "struct ifnet *ifp" "struct mbuf *m" "struct ieee80211_node *ni"
.Fa "int rssi" "u_int32_t rstamp"
.Fa "struct ieee80211_node *"
.Fa "struct mbuf *"
.Fa "int rssi"
.Fa "int noise"
.Fc
.Ft struct mbuf *
.Fn ieee80211_decap "struct ifnet *ifp" "struct mbuf *m"
.Ft void
.Fo ieee80211_recv_mgmt
.Fa "struct ieee80211com *ic" "struct mbuf *m0" "struct ieee80211_node *ni"
.Fa "int subtype" "int rssi" "u_int32_t rstamp"
.Fo ieee80211_input_all
.Fa "struct ieee80211com *"
.Fa "struct mbuf *"
.Fa "int rssi"
.Fa "int noise"
.Fc
.Sh DESCRIPTION
These
functions process received 802.11 frames.
.Pp
.\"
The
.Nm net80211
layer that supports 802.11 device drivers requires that
receive processing be single-threaded.
Typically this is done using a dedicated driver
.Xr taskqueue 9
thread.
.Fn ieee80211_input
function takes an mbuf chain
.Fa m
containing a complete 802.11 frame from the driver
.Fa ifp
and passes it to the software 802.11 stack for input processing.
The
.Fa ni
argument specifies an instance of
.Vt struct ieee80211_node
(which may be driver-specific) representing the node from which the
frame was received.
The arguments
.Fa rssi
and
.Fa stamp
are typically derived from on-card data structures; they are used for
recording the signal strength and time received of the frame respectively.
.Fn ieee80211_input_all
process received 802.11 frames and are designed
for use in that context; e.g. no driver locks may be held.
.Pp
.\"
The
.Fn ieee80211_decap
function performs decapsulation of the 802.11 frame in the mbuf chain
.Fa m
received by the device
.Fa ifp ,
taking the form of the 802.11 address fields into account;
the structure of 802.11 addresses vary according to the intended
source and destination of the frame.
It is typically called from within
.Fn ieee80211_input .
The frame passed up in the
.Vt mbuf
must have the 802.11 protocol header at the front; all device-specific
information and/or PLCP must be removed.
Any CRC must be stripped from the end of the frame.
The 802.11 protocol header should be 32-bit aligned for
optimal performance but receive processing does not require it.
If the frame holds a payload and that is not aligned to a 32-bit
boundary then the payload will be re-aligned so that it is suitable
for processing by protocols such as
.Xr ip 4 .
.Pp
If a device (such as
.Xr ath 4 )
inserts padding after the 802.11 header to align
the payload to a 32-bit boundary the
.Dv IEEE80211_C_DATAPAD
capability must be set.
Otherwise header and payload are assumed contiguous in the mbuf chain.
.Pp
If a received frame must pass
through the A-MPDU receive reorder buffer then the mbuf
must be marked with the
.Dv M_AMPDU
flag.
Note that for the moment this is required of all frames received from
a station and TID where a Block ACK stream is active, not just A-MPDU
aggregates.
It is sufficient to check for
.Dv IEEE80211_NODE_HT
in the
.Vt ni_flags
of the station's node table entry, any frames that do not require reorder
processing will be dispatched with only minimal overhead.
.Pp
.\"
The
.Fn ieee80211_recv_mgmt
performs input processing for 802.11 management frames.
It is typically called from within
.Fn ieee80211_input .
.\"
.Vt rssi
parameter is the Receive Signal Strength Indication of the frame
measured in 0.5dBm units relative to the noise floor.
The
.Vt noise
parameter is the best approximation of the noise floor in
dBm units at the time the frame was received.
RSSI and noise are used by the
.Nm net80211
layer to make scanning and roaming decisions in station mode
and to do auto channel selection for hostap and similar modes.
Otherwise the values are made available to user applications
(with the rssi presented as a filtered average over the last ten values
and the noise floor the last reported value).
.Sh SEE ALSO
.Xr ieee80211 9 ,
.Xr ifnet 9
.Sh HISTORY
The
.Nm ieee80211
series of functions first appeared in
.Nx 1.5 ,
and were later ported to
.Fx 4.6 .
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
and
.An Darron Broad Aq darron@kewl.org .
.Sh BUGS
There is no netisr queue specifically for the software 802.11 stack yet.
.Xr ieee80211 9 .

92
share/man/man9/ieee80211_ioctl.9
View File

@ -1,92 +0,0 @@
.\"
.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
.\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
.\" 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$
.\" $Id: ieee80211_ioctl.9,v 1.5 2004/03/04 12:33:27 bruce Exp $
.\"
.Dd March 2, 2004
.Dt IEEE80211_IOCTL 9
.Os
.Sh NAME
.Nm ieee80211_cfgget , ieee80211_cfgset , ieee80211_ioctl
.Nd 802.11 interface ioctl commands
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.In net80211/ieee80211_proto.h
.In net80211/ieee80211_ioctl.h
.Ft int
.Fn ieee80211_cfgget "struct ifnet *ifp" "u_long cmd" "caddr_t data"
.Ft int
.Fn ieee80211_cfgset "struct ifnet *ifp" "u_long cmd" "caddr_t data"
.Ft int
.Fn ieee80211_ioctl "struct ifnet *ifp" "u_long cmd" "caddr_t data"
.Sh DESCRIPTION
These
functions are typically invoked by drivers in response to requests
for information or to change settings from the userland.
.Pp
.\"
The
.Fn ieee80211_cfgget
and
.Fn ieee80211_cfgset
functions implement a legacy interface for getting and setting 802.11
interface attributes respectively.
.Pp
.\"
The
.Fn ieee80211_ioctl
function provides a default implementation of the
.Dv SIOCS80211
and
.Dv SIOCG80211
ifioctls commands for 802.11 drivers.
The call signature is identical to that of the
.Va if_ioctl
member found in
.Vt struct ifnet ,
however, many drivers store attributes such as
.Dv IEEE80211_IOC_STATIONNAME
in the driver's private soft state structure, so driver writers may prefer
to use this as the catch-all in a switch statement to avoid code duplication.
.\"
.Sh SEE ALSO
.Xr ifconfig 8 ,
.Xr ieee80211 9 ,
.Xr ifnet 9
.Sh HISTORY
The
.Nm ieee80211
series of functions first appeared in
.Nx 1.5 ,
and were later ported to
.Fx 4.6 .
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
and
.An Darron Broad Aq darron@kewl.org .

452
share/man/man9/ieee80211_node.9
View File

@ -25,269 +25,227 @@
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\" $Id: ieee80211_node.9,v 1.6 2004/03/04 12:33:27 bruce Exp $
.\"
.Dd July 4, 2004
.Dd August 4, 2009
.Dt IEEE80211_NODE 9
.Os
.Sh NAME
.Nm ieee80211_node_attach ,
.Nm ieee80211_node_lateattach ,
.Nm ieee80211_node_detach ,
.Nm ieee80211_begin_scan ,
.Nm ieee80211_next_scan ,
.Nm ieee80211_create_ibss ,
.Nm ieee80211_end_scan ,
.Nm ieee80211_alloc_node ,
.Nm ieee80211_dup_bss ,
.Nm ieee80211_find_node ,
.Nm ieee80211_lookup_node ,
.Nm ieee80211_free_node ,
.Nm ieee80211_free_allnodes ,
.Nm ieee80211_timeout_nodes ,
.Nm ieee80211_iterate_nodes
.Nm ieee80211_node
.Nd software 802.11 stack node management functions
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.In net80211/ieee80211_proto.h
.In net80211/ieee80211_node.h
.Ft void
.Fn ieee80211_node_attach "struct ifnet *ifp"
.Ft void
.Fn ieee80211_node_lateattach "struct ifnet *ifp"
.Ft void
.Fn ieee80211_node_detach "struct ifnet *ifp"
.Ft void
.Fn ieee80211_begin_scan "struct ifnet *ifp"
.Ft void
.Fn ieee80211_next_scan "struct ifnet *ifp"
.Ft void
.Fo ieee80211_create_ibss
.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
.\"
.Ft struct ieee80211_node *
.Fo ieee80211_find_rxnode
.Fa "struct ieee80211com *"
.Fa "const struct ieee80211_frame_min *"
.Fc
.Ft void
.Fn ieee80211_end_scan "struct ifnet *ifp"
.\"
.Ft struct ieee80211_node *
.Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr"
.Ft struct ieee80211_node *
.Fn ieee80211_dup_bss "struct ieee80211com *ic" "u_int8_t *macaddr"
.Ft struct ieee80211_node *
.Fn ieee80211_find_node "struct ieee80211com *ic" "u_int8_t *macaddr"
.Ft struct ieee80211_node *
.Fo ieee80211_lookup_node
.Fa "struct ieee80211com *ic" "u_int8_t *macaddr"
.Fa "struct ieee80211_channel *chan"
.Fo ieee80211_find_rxnode_withkey
.Fa "struct ieee80211com *"
.Fa "const struct ieee80211_frame_min *"
.Fa "ieee80211_keyix"
.Fc
.\"
.Ft struct ieee80211_node *
.Fn ieee80211_ref_node "struct ieee80211_node *"
.\"
.Ft void
.Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni"
.Fn ieee80211_unref_node "struct ieee80211_node *"
.\"
.Ft void
.Fn ieee80211_free_allnodes "struct ieee80211com *ic"
.Ft void
.Fn ieee80211_timeout_nodes "struct ieee80211com *ic"
.Fn ieee80211_free_node "struct ieee80211_node *"
.\"
.Ft void
.Fo ieee80211_iterate_nodes
.Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg"
.Fa "struct ieee80211_node_table *"
.Fa "ieee80211_iter_func *f"
.Fa "void *arg"
.Fc
.\"
.Ft void
.Fo ieee80211_dump_nodes
.Fa "struct ieee80211_node_table *"
.Fc
.\"
.Ft void
.Fo ieee80211_dump_node
.Fa "struct ieee80211_node *"
.Fc
.Sh DESCRIPTION
These functions are used to manage node lists within the software
802.11 stack.
These lists are typically used for implementing host-mode AP functionality,
or providing signal quality information about neighbouring nodes.
The
.Nm net80211
layer that supports 802.11 device drivers maintains a database of
peer stations called the
.Dq node table
in the
.Vt ic_sta
entry of the
.Vt ieee80211com
structure.
Station mode vaps create an entry for the access point
the station is associated to.
AP mode vaps create entries for associated stations.
Adhoc and mesh mode vaps create entries for neighbor stations.
WDS mode vaps create an entry for the peer station.
Stations for all vaps reside in the same table; each node
entry has a
.Vt ni_vap
field that identifies the vap that created it.
In some instances an entry is used by multiple vaps (e.g. for
dynamic WDS a station associated to an ap vap may also be the peer
of a WDS vap).
.Pp
.\"
Node table entries are reference counted.
That is, there is a count of all long term references that determines
when an entry may be reclaimed.
References are held by every in-flight frame sent to a station to
insure the entry is not reclaimed while the frame is queued or otherwise
held by a driver.
Routines that lookup a table entry return a
.Dq held reference
(i.e. a pointer to a table entry with the reference count incremented).
The
.Fn ieee80211_node_attach
function is called from
.Xr ieee80211_ifattach 9
to initialize node database management callbacks for the interface
.Fa ifp
(specifically for memory allocation, node copying and node
signal inspection).
These functions may be overridden in special circumstances,
as long as this is done after calling
.Xr ieee80211_ifattach 9
and prior to any other call which may allocate a node.
.Pp
.\"
The
.Fn ieee80211_node_lateattach
function initialises the
.Va ic_bss
node element of the interface
.Fa ifp
during
.Xr ieee80211_media_init 9 .
This late attachment is to account for certain special cases described under
.Fn ieee80211_node_attach .
.Pp
.\"
The
.Fn ieee80211_node_detach
function destroys all node database state associated with the interface
.Fa ifp ,
and is usually called during device detach.
.Pp
.\"
The
.Fn ieee80211_begin_scan
function initialises the node database in preparation of an active
scan for an access point on the interface
.Fa ifp .
The scan begins on the next radio channel by calling
.Fn ieee80211_next_scan
internally.
The actual scanning for an access point is not automated;
the device driver itself only handles setting the radio frequency
of the card and stepping through the channels.
.Pp
.\"
The
.Fn ieee80211_next_scan
function is used to inform the
.Xr ieee80211 9
layer that the interface
.Fa ifp
is now scanning for an access point on the next radio channel.
A device driver is expected to first call
.Fn ieee80211_begin_scan ,
to initialize the node database,
then set the radio channel on the device;
then, after a certain time has elapsed (200ms for example), call
.Fn ieee80211_next_scan
to move to the next channel.
Typically, a callout is used to automate this process; see
.Xr callout_init 9
for more information on how to use callouts.
.Pp
.\"
The
.Fn ieee80211_create_ibss
function sets up the net80211-specific portion of an interface's softc,
.Fa ic ,
for use in IBSS mode.
.Pp
.\"
The
.Fn ieee80211_end_scan
function is called by
.Fn ieee80211_next_scan
when the state machine has peformed a full cycle of scanning on
all available radio channels.
Internally,
.Fn ieee80211_end_scan
will inspect the node cache associated with the interface
.Fa ifp
for suitable access points found during scanning, and associate with one,
should the parameters of the node match those of the configuration
requested from userland.
.Pp
.\"
The
.Fn ieee80211_alloc_node
function allocates an instance of
.Vt "struct ieee80211_node"
for a node having the MAC address
.Fa macaddr ,
and associates it with the interface
.Fa ic .
If the allocation is successful, the node structure is initialised by
.Fn ieee80211_setup_node ;
otherwise,
.Dv NULL
is returned.
.Pp
.\"
The
.Fn ieee80211_dup_bss
function is similar to
.Fn ieee80211_alloc_node ,
but is instead used to create a node database entry for the BSSID
.Fa macaddr
associated with the interface
.Fa ic .
If the allocation is successful, the node structure is initialised by
.Fn ieee80211_setup_node ;
otherwise,
.Dv NULL
is returned.
.Pp
.\"
The
.Fn ieee80211_find_node
function will iterate through the node list associated with the interface
.Fa ic ,
searching for a node entry which matches
.Fa macaddr .
If the entry is found, its reference count is incremented, and
a pointer to the node is returned; otherwise,
.Dv NULL
will be returned.
.Pp
.\"
The
.Fn ieee80211_lookup_node
function is similar to
.Fn ieee80211_find_node ,
with an additional argument
.Fa chan
which is used to specify a channel for the match.
If the entry is found, its reference count is incremented, and
a pointer to the node is returned; otherwise,
.Dv NULL
will be returned.
.Pp
.\"
The
.Fn ieee80211_free_node
function will remove the node
.Fa ni
from the node database entries associated with the interface
.Fa ic ,
and free any memory associated with the node.
This private method can be overridden in
.Fn ieee80211_node_attach .
.\"
.Pp
The
.Fn ieee80211_free_allnodes
function will iterate through the node list calling
.Fn ieee80211_free_node
for all nodes associated with the interface
.Fa ic .
.Pp
.\"
The
.Fn ieee80211_timeout_nodes
checks if the inactivity timer of each node associated with the interface
.Fa ic
has exceeded the pre-defined constant
.Dv IEEE80211_INACT_MAX .
If so, then the node is freed, after sending a deauthentication message.
.Pp
.\"
The
.Fn ieee80211_iterate_nodes
function will call the user-defined callback function
.Fa f
for all nodes in the node database associated with the interface
.Fa ic .
The callback is invoked with the with the user-supplied value
.Fa arg
and a pointer to the current node.
.\"
.Sh SEE ALSO
.Xr ieee80211 9 ,
.Xr ifnet 9
.Sh HISTORY
The
.Nm ieee80211
series of functions first appeared in
.Nx 1.5 ,
and were later ported to
.Fx 4.6 .
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
.Fn ieee80211_ref_node
and
.An Darron Broad Aq darron@kewl.org .
.Fn ieee80211_unref_node
calls explicitly increment/decrement the reference count of a node,
but are rarely used.
Instead most callers use
.Fn ieee80211_free_node
to release a reference and, if the count goes to zero, reclaim the
table entry.
.Pp
The station table and its entries are exposed to drivers in several ways.
Each frame transmitted to a station includes a reference to the
associated node in the
.Vt m_pkthdr.rcvif
field.
This reference must be reclaimed by the driver when transmit processing
is done.
For each frame received the driver must lookup the table entry to
use in dispatching the frame
.Dq up the stack .
This lookup implicitly obtains a reference to the table entry and
the driver must reclaim the reference when frame processing is completed.
Otherwise drivers frequently inspect the contents of the
.Vt iv_bss
node when handling state machine changes as important information
is maintained in the data structure.
.Pp
The node table is opaque to drivers.
Entries may be looked up using one of the pre-defined API's or the
.Fn ieee80211_iterate_nodes
call may be used to iterate through all entries to do per-node
processing or implement some non-standard search mechanism.
Note that
.Fn ieee80211_iterate_nodes
is single-threaded per-device
and the effort processing involved is fairly
substantial so it should be used carefully.
.Pp
Two routines are provided to print the contents of nodes to the console
for debugging:
.Fn ieee80211_dump_node
displays the contents of a single node while
.Fn ieee80211_dump_nodes
displays the contents of the specified node table.
Nodes may also be displayed using
.Xr ddb 9
with the
.Dq show node
directive and the station node table can be displayed with
.Dq show statab .
.Sh DRIVER PRIVATE STATE
Node data structures may be extended by the driver to include
driver-private state.
This is done by overriding the
.Vt ic_node_alloc
method used to allocate a node table entry.
The driver method must allocate a structure that is an extension
of the
.Vt ieee80211_node
structure.
For example the
.Xr iwi 4
driver defines a private node structure as:
.Bd -literal -offset indent
struct iwi_node {
struct ieee80211_node in_node;
int in_station;
};
.Ed
.Pp
and then provides a private allocation routine that does this:
.Bd -literal -offset indent
static struct ieee80211_node *
iwi_node_alloc(struct ieee80211vap *vap,
const uint8_t mac[IEEE80211_ADDR_LEN])
{
struct iwi_node *in;
in = malloc(sizeof (struct iwi_node), M_80211_NODE,
M_NOWAIT | M_ZERO);
if (in == NULL)
return NULL;
in->in_station = -1;
return &in->in_node;
}
.Ed
.Pp
Note that when reclaiming a node allocated by the driver the
.Dq parent method
must be called to ensure
.Nm net80211
state is reclaimed; for example:
.Bd -literal -offset indent
static void
iwi_node_free(struct ieee80211_node *ni)
{
struct ieee80211com *ic = ni->ni_ic;
struct iwi_softc *sc = ic->ic_ifp->if_softc;
struct iwi_node *in = (struct iwi_node *)ni;
if (in->in_station != -1)
free_unr(sc->sc_unr, in->in_station);
sc->sc_node_free(ni); /* invoke net80211 free handler */
}
.Ed
.Pp
Beware that care must be taken to avoid holding references that
might cause nodes from being reclaimed.
.Nm net80211
will reclaim a node when the last reference is reclaimed in
its data structures.
However if a driver holds additional references then
.Nm net80211
will not recognize this and table entries will not be reclaimed.
Such references should not be needed if the driver overrides the
.Vt ic_node_cleanup
and/or
.Vt ic_node_free
methods.
.Sh KEY TABLE SUPPORT
Node table lookups are typically done using a hash of the stations'
mac address.
When receiving frames this is sufficient to find the node table entry
for the transmitter.
But some devices also identify the sending station in the device
state received with each frame and this data can be used to optimize
lookups on receive using a companion table called the
.Dq keytab .
This table records a separate node table reference that can be fetched
without any locking using the table index.
This logic is handled with the
.Fn ieee80211_find_rxnode_withkey
call: if a keytab entry is found using the specified index then it is
returned directly; otherwise a normal lookup is done and the keytab
entry is written using the specified index.
If the specified index is
.Dv IEEE80211_KEYIX_NONE
then a normal lookup is done without a table update.
.Sh SEE ALSO
.Xr ddb 9
.Xr ieee80211 9 ,
.Xr ieee80211_proto 9 ,

255
share/man/man9/ieee80211_output.9
View File

@ -27,125 +27,168 @@
.\" $FreeBSD$
.\" $Id: ieee80211_output.9,v 1.5 2004/03/04 12:31:18 bruce Exp $
.\"
.Dd March 2, 2004
.Dd August 4, 2009
.Dt IEEE80211_OUTPUT 9
.Os
.Sh NAME
.Nm ieee80211_encap , ieee80211_add_rates ,
.Nm ieee80211_add_xrates , ieee80211_send_mgmt
.Nm ieee80211_output
.Nd software 802.11 stack output functions
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.In net80211/ieee80211_proto.h
.Ft struct mbuf *
.Fo ieee80211_encap
.Fa "struct ifnet *ifp" "struct mbuf *m" "struct ieee80211_node **pni"
.Fc
.Ft u_int8_t *
.Fn ieee80211_add_rates "u_int8_t *frm" "const struct ieee80211_rateset *rs"
.Ft u_int8_t *
.Fn ieee80211_add_xrates "u_int8_t *frm" "const struct ieee80211_rateset *rs"
.\"
.Ft int
.Fo ieee80211_send_mgmt
.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int type" "int arg"
.Fn M_WME_GETAC "struct mbuf *"
.\"
.Ft int
.Fn M_SEQNO_GET "struct mbuf *"
.\"
.Ft struct ieee80211_key *
.Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *"
.\"
.Ft void
.Fo ieee80211_process_callback
.Fa struct ieee80211_node *
.Fa struct mbuf *
.Fa int
.Fc
.Sh DESCRIPTION
These functions handle the encapsulation and transmission of 802.11 frames
within the software 802.11 stack.
.Pp
The
.Fn ieee80211_encap
function encapsulates an outbound data frame contained within the
mbuf chain
.Fa m
from the interface
.Fa ifp .
The argument
.Fa *pni
is a reference to the destination node.
.Nm net80211
layer that supports 802.11 device drivers handles most of the
work required to transmit frames.
Drivers usually receive fully-encapsulated 802.11 frames that
have been classified and assigned a transmit priority;
all that is left is to do
crypto encapsulation,
prepare any hardware-specific state,
and
push the packet out to the device.
Outbound frames are either generated by the
.Nm net80211
layer (e.g. management frames) or are passed down
from upper layers through the
.Xr ifnet 9
transmit queue.
Data frames passed down for transmit flow through
.Nm net80211
which handles aggregation, 802.11 encapsulation, and then
dispatches the frames to the driver through it's transmit queue.
.Pp
If the function is successful, the mbuf chain is updated with the
802.11 frame header prepended, and a pointer to the head of the chain
is returned.
If an error occurs,
.Dv NULL
will be returned, and
.Fa *pni
is also set to
.Dv NULL .
The caller is responsible for freeing the node reference if
.Fa *pni
is
.Pf non- Dv NULL
on return.
The convention is that
.Va ic_bss
is not reference counted; the caller is responsible for maintaining this
reference count.
There are two control paths by which frames reach a driver for transmit.
Data packets are queued to the device's
.Vt if_snd
queue and the driver's
.Vt if_start
method is called.
Other frames are passed down using the
.Vt ic_raw_xmit
method without queueing (unless done by the driver).
The raw transmit path may include data frames from user applications
that inject them through
.Xr bpf 4
and NullData frames generated by
.Nm net80211
to probe for idle stations (when operating as an access point).
.Pp
.\"
.Nm net80211
handles all state-related bookkeeping and management for the handling
of data frames.
Data frames are only transmit for a vap in the
.Dv IEEE80211_S_RUN
state; there is no need, for example, to check for frames sent down
when CAC or CSA is active.
Similarly,
.Nm net80211
handles activities such as background scanning and power save mode,
frames will not be sent to a driver unless it is operating on the
BSS channel will
.Dq full power .
.Pp
All frames passed to a driver for transmit hold a reference to a
node table entry in the
.Vt m_pkthdr.rcvif
field.
The node is associated with the frame destination.
Typically it is the receiver's entry but in some situations it may be
a placeholder entry or the
.Dq next hop station
(such as in a mesh network).
In all cases the reference must be reclaimed with
.Fn ieee80211_free_node
when the transmit work is completed.
The rule to remember is:
.Nm net80211
passes responsibility for the
.Vt mbuf
and
.Dq node reference
to the driver with each frame it hands off for transmit.
.Sh PACKET CLASSIFICATION
All frames passed by
.Nm net80211
for transmit are assigned a priority based on any vlan tag
assigned to the receiving station and/or any Diffserv setting
in an IP or IPv6 header.
If both vlan and Diffserv priority are present the higher of the
two is used.
If WME/WMM is being used then any ACM policy (in station mode) is
also enforced.
The resulting AC is attached to the mbuf and may be read back using the
.Fn M_WME_GETAC
macro.
.Pp
PAE/EAPOL frames are tagged with an
.Dv M_EAPOL
mbuf flag; drivers should transmit them with care, usually by
using the transmit rate for management frames.
Multicast/broadcast frames are marked with the
.Dv M_MCAST
mbuf flag.
Frames coming out of a station's power save queue and that have
more frames immediately following are marked with the
.Dv M_MORE_DATA
mbuf flag.
Such frames will be queued consecutively in the driver's
.Vt if_snd
queue and drivers should preserve the ordering when passing
them to the device.
.Sh FRAGMENTED FRAMES
The
.Fn ieee80211_add_rates
utility function is used to add the rate set element
.Fa *rs
to the frame
.Fa frm .
A pointer to the location in the buffer after the addition of the rate set
is returned.
It is typically used when constructing management frames from within the
software 802.11 stack.
.Pp
.\"
The
.Fn ieee80211_add_xrates
utility function is used to add the extended rate set element
.Fa *rs
to the frame
.Fa frm .
A pointer to the location in the buffer after the addition of the rate set
is returned.
It is typically used when constructing management frames from within the
software 802.11 stack in 802.11g mode.
.Pp
.\"
The
.Fn ieee80211_send_mgmt
function transmits a management frame on the interface
.Fa ic
to the destination node
.Fa ni
of type
.Fa type .
.Pp
The argument
.Fa arg
specifies either a sequence number for authentication operations,
a status code for [re]association operations,
or a reason for deauthentication and deassociation operations.
.Pp
Nodes other than
.Va ic_bss
have their reference count incremented to reflect their use for an
indeterminate amount of time.
This reference is freed when the function returns.
.Pp
The function returns 0 if successful; if temporary buffer space is not
available, the function returns
.Er ENOMEM .
.\"
.Nm net80211
layer will fragment data frames according to the setting of
.Vt iv_fragthreshold
if a driver marks the
.Dv IEEE80211_C_TXFRAG
capability.
Fragmented frames are placed
in the devices transmit queue with the fragments chained together with
.Vt m_nextpkt .
Each frame is marked with the
.Dv M_FRAG
mbuf flag, and the first and last are marked with
.Dv M_FIRSTFRAG
and
.Dv M_LASTFRAG ,
respectively.
Drivers are expected to process all fragments or none.
.Sh TRANSMIT CALLBACKS
Frames sent by
.Nm net80211
may be tagged with the
.Dv M_TXCB
mbuf flag to indicate a callback should be done
when their transmission completes.
The callback is done using
.Fn ieee80211_process_callback
with the last parameter set to a non-zero value if an error occurred
and zero otherwise.
Note
.Nm net80211
understands that drivers may be incapable of determining status;
a device may not report if an ACK frame is received and/or a device may queue
transmit requests in its hardware and only report status on whether
the frame was successfully queued.
.Sh SEE ALSO
.Xr bpf 4
.Xr ieee80211 9 ,
.Xr ifnet 9
.Sh HISTORY
The
.Nm ieee80211
series of functions first appeared in
.Nx 1.5 ,
and were later ported to
.Fx 4.6 .
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
and
.An Darron Broad Aq darron@kewl.org .

228
share/man/man9/ieee80211_proto.9
View File

@ -1,6 +1,5 @@
.\"
.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
.\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
.\" Copyright (c) 2009 Sam Leffler, Errno Consulting
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@ -25,51 +24,218 @@
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\" $Id: ieee80211_proto.9,v 1.5 2004/03/04 12:33:27 bruce Exp $
.\"
.Dd March 2, 2004
.Dd August 4, 2009
.Dt IEEE80211_PROTO 9
.Os
.Sh NAME
.Nm ieee80211_proto_attach ,
.Nm ieee80211_proto_detach ,
.Nm ieee80211_print_essid ,
.Nm ieee80211_dump_pkt ,
.Nm ieee80211_fix_rate ,
.Nm ieee80211_proto
.Nd software 802.11 stack protocol helper functions
.Nd 802.11 state machine support
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.In net80211/ieee80211_proto.h
.Pp
.Ft void
.Fn ieee80211_proto_attach "struct ifnet *ifp"
.Fn ieee80211_start_all "struct ieee80211com *"
.Ft void
.Fn ieee80211_proto_detach "struct ifnet *ifp"
.Fn ieee80211_stop_all "struct ieee80211com *"
.Ft void
.Fn ieee80211_print_essid "u_int8_t *essid" "int len"
.Fn ieee80211_suspend_all "struct ieee80211com *"
.Ft void
.Fn ieee80211_dump_pkt "u_int8_t *buf" "int len" "int rate" "int rssi"
.Fn ieee80211_resume_all "struct ieee80211com *"
.Pp
.Dv enum ieee80211_state ;
.Ft int
.Fo ieee80211_fix_rate
.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int flags"
.Fc
.Fn ieee80211_new_state "struct ieee80211vap *" "enum ieee80211_state" "int"
.Pp
.Ft void
.Fn ieee80211_wait_for_parent "struct ieee80211com *"
.Sh DESCRIPTION
These
functions are helper functions used throughout the software 802.11 protocol
stack.
The
.Nm net80211
layer that supports 802.11 device drivers uses a state machine
to control operation of vaps.
These state machines vary according to the vap operating mode.
Station mode state machines follow the 802.11 MLME states
in the protocol specification.
Other state machines are simpler and reflect operational work
such as scanning for a BSS or automatically selecting a channel to
operate on.
When multiple vaps are operational the state machines are used to
coordinate operation such as choosing a channel.
The state machine mechanism also serves to bind the
.Nm net80211
layer to a driver; this is described more below.
.Pp
The following states are defined for state machines:
.Bl -tag -width IEEE80211_S_ASSOC
.It Dv IEEE80211_S_INIT
Default/initial state.
A vap in this state should not hold any dynamic state (e.g. entries
for associated stations in the node table).
The driver must quiesce the hardware; e.g. there should be no
interrupts firing.
.It Dv IEEE80211_S_SCAN
Scanning for a BSS or choosing a channel to operate on.
Note that scanning can also take place in other states (e.g. when
background scanning is active); this state is entered when
initially bringing a vap to an operational state or after an
event such as a beacon miss (in station mode).
.It Dv IEEE80211_S_AUTH
Authenticating to an access point (in station mode).
This state is normally reached from
.Dv IEEE80211_S_SCAN
after selecting a BSS, but may also be reached from
.Dv IEEE80211_S_ASSOC
or
.Dv IEEE80211_S_RUN
if the authentication handshake fails.
.It Dv IEEE80211_S_ASSOC
Associating to an access point (in station mode).
This state is reached from
.Dv IEEE80211_S_AUTH
after successfully authenticating or from
.Dv IEEE80211_S_RUN
if a DisAssoc frame is received.
.It Dv IEEE80211_S_CAC
Doing Channel Availability Check (CAC).
This state is entered only when DFS is enabled and the channel selected
for operation requires CAC.
.It Dv IEEE80211_S_RUN
Operational.
In this state a vap can transmit data frames, accept requests for
stations associating, etc.
Beware that data traffic is also gated by whether the associated
.Dq port
is authorized.
When WPA/802.11i/802.1x is operational authorization may happen separately;
e.g. in station mode
.Xr wpa_supplicant 8
must complete the handshakes and plumb the necessary keys before a port
is authorized.
In this state a BSS is operational and associated state is valid and may
be used; e.g.
.Vt ic_bss
and
.Vt ic_bsschan
are guaranteed to be usable.
.It Dv IEEE80211_S_CSA
Channel Switch Annoucememnt (CSA) is pending.
This state is reached only from
.Dv IEEE80211_S_RUN
when either a CSA is received from an access point (in station mode)
or the local station is preparing to change channel.
In this state traffic may be muted depending on the Mute setting in the CSA.
.It Dv IEEE80211_S_SLEEP
Asleep to save power (in station mode).
This state is reached only from
.Dv IEEE80211_S_RUN
when power save operation is enabled and the local station is deemed
sufficiently idle to enter low power mode.
.El
.Pp
Note that states are ordered (as shown above);
e.g. a vap must be in the
.Dv IEEE80211_S_RUN
or
.Dq greater
before it can transmit frames.
Certain
.Nm net80211
data are valid only in certain states; e.g. the
.Vt iv_bsschan
that specifies the channel for the operating BSS should never be used
except in
.Dv IEEE80211_S_RUN
or greater.
.Sh STATE CHANGES
State machine changes are typically handled internal to the
.Nm net80211
layer in response to
.Xr ioctl 2
requests, received frames, or external events such as a beacon miss.
The
.Fn ieee80211_new_state
function is used to initiate a state machine change on a vap.
The new state and an optional argument are supplied.
The request is initially processed to handle coordination of multiple vaps.
For example, only one vap at a time can be scanning, if multiple vaps
request a change to
.Dv IEEE80211_S_SCAN
the first will be permitted to run and the others will be
.Em deferred
until the scan operation completes at which time the selected channel
will be adopted.
Similarly
.Nm net80211
handles coordination of combinations of vaps such as an AP and station vap
where the station may need to roam to follow the AP it is associated to
(dragging along the AP vap to the new channel).
Another important coordination is the handling of
.Dv IEEE80211_S_CAC
and
.Dv IEEE80211_S_CSA .
No more than one vap can ever be actively changing state at a time.
In fact
.Nm net80211
single-threads the state machine logic in a dedicated
.Xr taskqueue 9
thread that is also used to synchronize work such as scanning and
beacon miss handling.
.Pp
After multi-vap scheduling/coordination is done the per-vap
.Vt iv_newstate
method is called to carry out the state change work.
Drivers use this entry to setup private state and then dispatch
the call to the
.Nm net80211
layer using the previously defined method pointer (in OOP-parlance they
call the
.Dq super method
).
.Pp
.Nm net80211
handles two state changes specially.
On transition to
.Dv IEEE80211_S_RUN
the
.Dv IFF_DRV_OACTIVE
bit on the vap's transmit queue is cleared so traffic can flow.
On transition to
.Dv IEEE80211_S_INIT
any state in the scan cache associated with the vap is flushed
and any frames pending on the transmit queue are flushed.
.Sh DRIVER INTEGRATION
Drivers are expected to override the
.Vt iv_newstate
method to interpose their own code and handle setup work required
by state changes.
Otherwise drivers must call
.Fn ieee80211_start_all
in response to being marked up through an
.Dv SIOCSIFFLAGS
ioctl request and they should use
.Fn ieee80211_suspend_all
and
.Fn ieee80211_resume_all
to implement suspend/resume support.
.Pp
There is also an
.Fn ieee80211_stop_all
call to force all vaps to an
.Dv IEEE80211_S_INIT
state but this should not be needed by a driver; control is usually
handled by
.Nm net80211
or, in the case of card eject or vap destroy,
work will be initiated outside the driver.
.Sh SEE ALSO
.Xr ioctl 2
.Xr ieee80211 9 ,
.Xr ifnet 9
.Xr taskqueue 9
.Xr wpa_supplicant 8
.Sh HISTORY
The
The state machine concept was part of the original
.Nm ieee80211
series of functions first appeared in
code base that first appeared in
.Nx 1.5 ,
and were later ported to
.Fx 4.6 .
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
and
.An Darron Broad Aq darron@kewl.org .

358
share/man/man9/ieee80211_radiotap.9
View File

@ -26,210 +26,280 @@
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\" $Id: ieee80211_radiotap.9,v 1.3 2004/03/04 11:38:52 bruce Exp $
.\"
.Dd March 17, 2008
.Dd August 4, 2009
.Dt IEEE80211_RADIOTAP 9
.Os
.Sh NAME
.Nm ieee80211_radiotap
.Nd software 802.11 stack packet capture definitions
.Nd 802.11 device packet capture support
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.In net80211/ieee80211_ioctl.h
.In net80211/ieee80211_radiotap.h
.In net/bpf.h
.\"
.Pp
.Ft void
.Fo ieee80211_radiotap_attach
.Fa "struct ieee80211com *"
.Fa "struct ieee80211_radiotap_header *th"
.Fa "int tlen"
.Fa "uint32_t tx_radiotap"
.Fa "struct ieee80211_radiotap_header *rh"
.Fa "int rlen"
.Fa "uint32_t rx_radiotap"
.Fc
.\"
.Ft int
.Fn ieee80211_radiotap_active_vap "struct ieee80211vap *"
.\"
.Ft int
.Fn ieee80211_radiotap_active "struct ieee80211com *"
.\"
.Ft void
.Fn ieee80211_radiotap_tx "struct ieee80211vap *" "struct mbuf *"
.Sh DESCRIPTION
The
.Nm
definitions provide a device-independent
.Xr bpf 4
attachment for the
capture of information about 802.11 traffic which is not part of
the 802.11 frame structure.
.Nm net80211
layer used by 802.11 drivers includes support for a device-independent
packet capture format called
.Nm radiotap
that is understood by tools such as
.Xr tcpdump 1 .
This facility is designed for capturing 802.11 traffic,
including information that is not part of the normal 802.11 frame structure.
.Pp
Radiotap was designed to balance the desire for a capture format
that conserved CPU and memory bandwidth on embedded systems,
with the desire for a hardware-independent, extensible format
that would support the diverse capabilities of virtually all
802.11
radios.
.Pp
These considerations led radiotap to settle on a format consisting of
Radiotap was designed to balance the desire for a hardware-independent,
extensible capture format against the need to
conserve CPU and memory bandwidth on embedded systems.
These considerations led to a format consisting of
a standard preamble followed by an extensible bitmap indicating the
presence of optional capture fields.
A
.Nm net80211
device driver supporting
.Vt radiotap
defines two packed structures that it shares with
.Nm net80211 .
These structures embed an instance of a
.Vt ieee80211_radiotap_header
structure at the beginning,
with subsequent fields in the appropriate order,
and macros to set the bits of the
.Va it_present
bitmap to indicate which fields exist and are filled in by the driver.
This information is then supplied through the
.Fn ieee80211_radiotap_attach
call after a successful
.Fn ieee80211_ifattach
request.
.Pp
The capture fields were packed into the header as compactly as possible,
modulo the requirements that they had to be packed swiftly,
with suitable alignment, in the same order as the bits indicating
their presence.
With radiotap setup, drivers just need to fill in per-packet
capture state for frames sent/received and dispatch capture state
in the transmit path (since control is not returned to the
.Nm net80211
layer before the packet is handed to the device).
To minimize overhead this work should be done only when one
or more processes are actively capturing data;
this is checked with one of
.Fn ieee80211_radiotap_active_vap
and
.Fn ieee80211_radiotap_active .
In the transmit path capture work looks like this:
.Pp
This typically includes information such as signal quality and
timestamps.
This information may be used by a variety of user agents, including
.Xr tcpdump 1 .
It is requested by using the
.Xr bpf 4
data-link type
.Dv DLT_IEEE802_11_RADIO .
.Pp
.\"
Each frame using this attachment has the following header prepended to it:
.Bd -literal -offset indent
struct ieee80211_radiotap_header {
u_int8_t it_version; /* set to 0 */
u_int8_t it_pad;
u_int16_t it_len; /* entire length */
u_int32_t it_present; /* fields present */
} __attribute__((__packed__));
if (ieee80211_radiotap_active_vap(vap)) {
... /* record transmit state */
ieee80211_radiotap_tx(vap, m); /* capture transmit event */
}
.Ed
.Pp
While in the receive path capture is handled in
.Nm net80211
but state must be captured before dispatching a frame:
.Pp
.Bd -literal -offset indent
if (ieee80211_radiotap_active(ic)) {
... /* record receive state */
}
\&...
ieee80211_input(...); /* packet capture handled in net80211 */
.Ed
.Pp
.\"
A device driver implementing
.Vt radiotap
typically defines a packed structure embedding an instance of
.Vt "struct ieee80211_radiotap_header"
at the beginning,
with subsequent fields in the appropriate order,
and a macro to set the bits of the
.Va it_present
bitmap to indicate which fields exist and are filled in by the driver.
.\"
.Pp
Radiotap headers are copied to the userland via a separate bpf attachment.
It is necessary for the driver to create this attachment after calling
.Xr ieee80211_ifattach 9
by calling
.Fn bpfattach2
with the data-link type set to
.Dv DLT_IEEE802_11_RADIO .
.Pp
.\"
When the the information is available,
usually immediately before a link-layer transmission or after a receive,
the driver copies it to the bpf layer using the
.Fn bpf_mtap2
function.
.Pp
.\"
The following extension fields are defined for
The following fields are defined for
.Vt radiotap ,
in the order in which they should appear in the buffer copied to userland:
in the order in which they should appear in the buffer supplied
to
.Nm net80211 .
.Bl -tag -width indent
.It Dv IEEE80211_RADIOTAP_TSFT
This field contains the unsigned 64-bit value, in microseconds,
of the MAC's 802.11 Time Synchronization Function timer,
of the MAC's 802.11 Time Synchronization Function (TSF).
In theory, for each received frame, this value is recorded
when the first bit of the MPDU arrived at the MAC.
This field should be present for received frames only.
In practice, hardware snapshots the TSF otherwise and one cannot assume
this data is accurate without driver adjustment.
.It Dv IEEE80211_RADIOTAP_FLAGS
This field contains a single unsigned 8-bit value, containing a bitmap
of flags specifying properties of the frame being transmitted or received.
This field contains a single unsigned 8-bit value, containing one or
more of these bit flags:
.Bl -tag -width indent
.It Dv IEEE80211_RADIOTAP_F_CFP
Frame was sent/received during the Contention Free Period (CFP).
.It Dv IEEE80211_RADIOTAP_F_SHORTPRE
Frame was sent/received with short preamble.
.It Dv IEEE80211_RADIOTAP_F_WEP
Frame was encrypted.
.It Dv IEEE80211_RADIOTAP_F_FRAG
Frame was an 802.11 fragment.
.It Dv IEEE80211_RADIOTAP_F_FCS
Frame contents includes the FCS.
.It Dv IEEE80211_RADIOTAP_F_DATAPAD
Frame contents potentially has padding between the 802.11 header and the
data payload to align the payload to a 32-bit boundary.
.It Dv IEEE80211_RADIOTAP_F_BADFCS
Frame was received with an invalid FCS.
.It Dv IEEE80211_RADIOTAP_F_SHORTGI
Frame was sent/received with Short Guard Interval.
.El
.It Dv IEEE80211_RADIOTAP_RATE
This field contains a single unsigned 8-bit value, which is the data rate in
use in units of 500Kbps.
This field contains a single unsigned 8-bit value that is the data rate.
Legacy rates are in units of 500Kbps.
MCS rates (used on 802.11n/HT channels) have the high bit set and
the MCS in the low 7 bits.
.It Dv IEEE80211_RADIOTAP_CHANNEL
This field contains two unsigned 16-bit values.
The first value is the frequency upon which this PDU was transmitted
or received.
The second value is a bitmap containing flags which specify properties of
the channel in use.
These are documented within the header file,
.In net80211/ieee80211_radiotap.h .
.It Dv IEEE80211_RADIOTAP_FHSS
This field contains two 8-bit values.
This field should be present for frequency-hopping radios only.
The first byte is the hop set.
The second byte is the pattern in use.
The first value is the center frequency for the channel
the frame was sent/received on.
The second value is a bitmap containing flags that specify channel properties.
.Pp
This field is deprecated in favor of
.Dv IEEE80211_RADIOTAP_XCHANNEL
but may be used to save space in the capture file for legacy devices.
.\".It Dv IEEE80211_RADIOTAP_FHSS
.\"This field contains two 8-bit values.
.\"This field should be present only for frequency-hopping radios.
.\"The first byte is the hop set.
.\"The second byte is the pattern in use.
.It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL
This field contains a single signed 8-bit value, which indicates the
This field contains a single signed 8-bit value that indicates the
RF signal power at the antenna, in decibels difference from 1mW.
.It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE
This field contains a single signed 8-bit value, which indicates the
This field contains a single signed 8-bit value that indicates the
RF noise power at the antenna, in decibels difference from 1mW.
.It Dv IEEE80211_RADIOTAP_LOCK_QUALITY
This field contains a single unsigned 16-bit value, indicating the
quality of the Barker Code lock.
No unit is specified for this field.
There does not appear to be a standard way of measuring this at this time;
this quantity is often referred to as
.Dq "Signal Quality"
in some datasheets.
.It Dv IEEE80211_RADIOTAP_TX_ATTENUATION
This field contains a single unsigned 16-bit value, expressing transmit
power as unitless distance from maximum power set at factory calibration.
0 indicates maximum transmit power.
Monotonically nondecreasing with lower power levels.
.It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION
This field contains a single unsigned 16-bit value, expressing transmit
power as decibel distance from maximum power set at factory calibration.
0 indicates maximum transmit power.
Monotonically nondecreasing with lower power levels.
.\".It Dv IEEE80211_RADIOTAP_LOCK_QUALITY
.\"This field contains a single unsigned 16-bit value, indicating the
.\"quality of the Barker Code lock.
.\"No unit is specified for this field.
.\"There does not appear to be a standard way of measuring this at this time;
.\"this quantity is often referred to as
.\".Dq "Signal Quality"
.\"in some datasheets.
.\".It Dv IEEE80211_RADIOTAP_TX_ATTENUATION
.\"This field contains a single unsigned 16-bit value, expressing transmit
.\"power as unitless distance from maximum power set at factory calibration.
.\"0 indicates maximum transmit power.
.\"Monotonically nondecreasing with lower power levels.
\.".It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION
\."This field contains a single unsigned 16-bit value, expressing transmit
\."power as decibel distance from maximum power set at factory calibration.
\."0 indicates maximum transmit power.
\."Monotonically nondecreasing with lower power levels.
.It Dv IEEE80211_RADIOTAP_DBM_TX_POWER
Transmit power expressed as decibels from a 1mW reference.
This field is a single signed 8-bit value.
This is the absolute power level measured at the antenna port.
.It Dv IEEE80211_RADIOTAP_ANTENNA
For radios which support antenna diversity, this field contains a single
unsigned 8-bit value specifying which antenna is being used to transmit
or receive this frame.
The first antenna is antenna 0.
This field contains a single unsigned 8-bit value that specifies
which antenna was used to transmit or receive the frame.
Antenna numbering is device-specific but typically the primary antenna has
the lowest number.
On transmit a value of zero may be seen which typically means
antenna selection is left to the device.
.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL
This field contains a single unsigned 8-bit value, which indicates the
This field contains a single unsigned 8-bit value that indicates the
RF signal power at the antenna, in decibels difference from an
arbitrary, fixed reference.
.It Dv IEEE80211_RADIOTAP_DB_ANTNOISE
This field contains a single unsigned 8-bit value, which indicates the
This field contains a single unsigned 8-bit value that indicates the
RF noise power at the antenna, in decibels difference from an
arbitrary, fixed reference.
.It Dv IEEE80211_RADIOTAP_EXT
This bit is reserved for any future extensions to the
.Vt radiotap
structure.
It should not be used at this time.
.It Dv IEEE80211_RADIOTAP_XCHANNEL
This field containts four values: a 32-bit unsigned bitmap of
flags that describe the channel attributes, a 16-bit unsigned
freqeuncy in MHz (typically the channel center), an 8-bit
unsigned IEEE channel number, and a signed 8-bit value that
holds the maximum regulatory transmit power cap in .5 dBm
(8 bytes total).
Channel flags are defined in:
.In net80211/_ieee80211.h
(only a subset are found in
.In net80211/ieee80211_radiotap.h ).
This property supersedes
.Dv IEEE80211_RADIOTAP_CHANNEL
and is the only way to completely express all
channel attributes and the
mapping between channel freqeuncy and IEEE channel number.
.El
.Sh EXAMPLES
Radiotap header for the Cisco Aironet driver:
Radiotap receive definitions for the Intersil Prims driver:
.Bd -literal -offset indent
struct an_rx_radiotap_header {
struct ieee80211_radiotap_header ar_ihdr;
u_int8_t ar_flags;
u_int8_t ar_rate;
u_int16_t ar_chan_freq;
u_int16_t ar_chan_flags;
u_int8_t ar_antsignal;
u_int8_t ar_antnoise;
} __attribute__((__packed__));
.Ed
.Pp
Bitmap indicating which fields are present in the above structure:
.Bd -literal -offset indent
#define AN_RX_RADIOTAP_PRESENT \\
((1 << IEEE80211_RADIOTAP_FLAGS) | \\
#define WI_RX_RADIOTAP_PRESENT \\
((1 << IEEE80211_RADIOTAP_TSFT) \\
(1 << IEEE80211_RADIOTAP_FLAGS) | \\
(1 << IEEE80211_RADIOTAP_RATE) | \\
(1 << IEEE80211_RADIOTAP_CHANNEL) | \\
(1 << IEEE80211_RADIOTAP_DBM_ANTSIGNAL) | \\
(1 << IEEE80211_RADIOTAP_DBM_ANTNOISE))
(1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \\
(1 << IEEE80211_RADIOTAP_DB_ANTNOISE))
struct wi_rx_radiotap_header {
struct ieee80211_radiotap_header wr_ihdr;
uint64_t wr_tsf;
uint8_t wr_flags;
uint8_t wr_rate;
uint16_t wr_chan_freq;
uint16_t wr_chan_flags;
uint8_t wr_antsignal;
uint8_t wr_antnoise;
} __packed;
.Ed
.Pp
and transmit definitions for the Atheros driver:
.Bd -literal -offset indent
#define ATH_TX_RADIOTAP_PRESENT ( \\
(1 << IEEE80211_RADIOTAP_TSFT) | \\
(1 << IEEE80211_RADIOTAP_FLAGS) | \\
(1 << IEEE80211_RADIOTAP_RATE) | \\
(1 << IEEE80211_RADIOTAP_DBM_TX_POWER) | \\
(1 << IEEE80211_RADIOTAP_ANTENNA) | \\
(1 << IEEE80211_RADIOTAP_XCHANNEL) | \\
0)
struct ath_tx_radiotap_header {
struct ieee80211_radiotap_header wt_ihdr;
uint64_t wt_tsf;
uint8_t wt_flags;
uint8_t wt_rate;
uint8_t wt_txpower;
uint8_t wt_antenna;
uint32_t wt_chan_flags;
uint16_t wt_chan_freq;
uint8_t wt_chan_ieee;
int8_t wt_chan_maxpow;
} __packed;
.Ed
.Sh SEE ALSO
.Xr tcpdump 1 ,
.Xr bpf 4 ,
.Xr ieee80211 9
.Sh HISTORY
The
.Nm
definitions first appeared in
.Nx 1.5 ,
and were later ported to
.Fx 4.6 .
.Nx 1.5 .
.\"
.Sh AUTHORS
.An -nosplit
The
.Nm
interface was designed and implemented by
.An David Young Aq dyoung@pobox.com .
.Pp
This manual page was written by
The original version of this manual page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
and
.An Darron Broad Aq darron@kewl.org .

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_countrie
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 .