Sync our ieee80211*(9) manual pages with FreeBSD.
authorSascha Wildner <saw@online.de>
Wed, 28 Apr 2010 12:47:13 +0000 (14:47 +0200)
committerSascha Wildner <saw@online.de>
Wed, 28 Apr 2010 12:54:32 +0000 (14:54 +0200)
16 files changed:
Makefile_upgrade.inc
share/man/man9/Makefile
share/man/man9/ieee80211.9
share/man/man9/ieee80211_amrr.9 [new file with mode: 0644]
share/man/man9/ieee80211_beacon.9 [new file with mode: 0644]
share/man/man9/ieee80211_bmiss.9 [new file with mode: 0644]
share/man/man9/ieee80211_crypto.9
share/man/man9/ieee80211_ddb.9 [copied from share/man/man9/ieee80211_proto.9 with 51% similarity]
share/man/man9/ieee80211_input.9
share/man/man9/ieee80211_node.9
share/man/man9/ieee80211_output.9
share/man/man9/ieee80211_proto.9
share/man/man9/ieee80211_radiotap.9
share/man/man9/ieee80211_regdomain.9 [new file with mode: 0644]
share/man/man9/ieee80211_scan.9 [new file with mode: 0644]
share/man/man9/ieee80211_vap.9 [new file with mode: 0644]

index 62f5d47..a2107c3 100644 (file)
@@ -1225,6 +1225,64 @@ TO_REMOVE+=/usr/share/man/cat9/ieee80211_cfgset.9.gz
 TO_REMOVE+=/usr/share/man/man9/ieee80211_cfgset.9.gz
 TO_REMOVE+=/usr/share/man/cat9/ieee80211_ioctl.9.gz
 TO_REMOVE+=/usr/share/man/man9/ieee80211_ioctl.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_add_rates.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_add_rates.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_add_ssid.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_add_ssid.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_add_xrates.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_add_xrates.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_begin_scan.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_begin_scan.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_chan2ieee.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_chan2ieee.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_chan2mode.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_chan2mode.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_create_ibss.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_create_ibss.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_dump_pkt.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_dump_pkt.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_encap.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_encap.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_end_scan.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_end_scan.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_find_node.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_find_node.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_find_txnode.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_find_txnode.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_fix_rate.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_fix_rate.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_free_node.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_free_node.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_ieee2mhz.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_ieee2mhz.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_media2rate.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_media2rate.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_media_change.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_media_change.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_media_init.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_media_init.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_media_status.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_media_status.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_mhz2ieee.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_mhz2ieee.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_next_scan.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_next_scan.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_print_essid.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_print_essid.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_proto_attach.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_proto_attach.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_proto_detach.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_proto_detach.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_rate2media.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_rate2media.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_recv_mgmt.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_recv_mgmt.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_send_mgmt.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_send_mgmt.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_setmode.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_setmode.9.gz
+TO_REMOVE+=/usr/share/man/cat9/ieee80211_watchdog.9.gz
+TO_REMOVE+=/usr/share/man/man9/ieee80211_watchdog.9.gz
 
 # XXX Remove when adjusted to the new 802.11 framework
 TO_REMOVE+=/boot/modules/if_acx.ko
index a80f7f4..76e81a2 100644 (file)
@@ -80,12 +80,19 @@ MAN=        accept_filter.9 \
        firmware.9 \
        hash.9 \
        ieee80211.9 \
+       ieee80211_amrr.9 \
+       ieee80211_beacon.9 \
+       ieee80211_bmiss.9 \
        ieee80211_crypto.9 \
+       ieee80211_ddb.9 \
        ieee80211_input.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 \
        intro.9 \
@@ -413,47 +420,83 @@ MLINKS+=ioctl.9 _IOR.9 \
        ioctl.9 _IOW.9 \
        ioctl.9 _IOWR.9 \
        ioctl.9 _IO.9
-MLINKS+=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_encap.9
-MLINKS+=ieee80211_input.9 ieee80211_recv_mgmt.9
-MLINKS+=ieee80211_node.9 ieee80211_begin_scan.9 \
-       ieee80211_node.9 ieee80211_create_ibss.9 \
-       ieee80211_node.9 ieee80211_end_scan.9 \
-       ieee80211_node.9 ieee80211_find_node.9 \
+MLINKS+=ieee80211.9 ieee80211_ifattach.9 \
+       ieee80211.9 ieee80211_ifdetach.9
+MLINKS+=ieee80211_amrr.9 ieee80211_amrr_choose.9 \
+       ieee80211_amrr.9 ieee80211_amrr_cleanup.9 \
+       ieee80211_amrr.9 ieee80211_amrr_init.9 \
+       ieee80211_amrr.9 ieee80211_amrr_node_init.9 \
+       ieee80211_amrr.9 ieee80211_amrr_setinterval.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_notify.9 \
+       ieee80211_beacon.9 ieee80211_beacon_update.9
+MLINKS+=ieee80211_bmiss.9 ieee80211_beacon_miss.9
+MLINKS+=ieee80211_crypto.9 ieee80211_crypto_available.9 \
+       ieee80211_crypto.9 ieee80211_crypto_decap.9 \
+       ieee80211_crypto.9 ieee80211_crypto_delglobalkeys.9 \
+       ieee80211_crypto.9 ieee80211_crypto_delkey.9 \
+       ieee80211_crypto.9 ieee80211_crypto_demic.9 \
+       ieee80211_crypto.9 ieee80211_crypto_encap.9 \
+       ieee80211_crypto.9 ieee80211_crypto_enmic.9 \
+       ieee80211_crypto.9 ieee80211_crypto_newkey.9 \
+       ieee80211_crypto.9 ieee80211_crypto_register.9 \
+       ieee80211_crypto.9 ieee80211_crypto_reload_keys.9 \
+       ieee80211_crypto.9 ieee80211_crypto_setkey.9 \
+       ieee80211_crypto.9 ieee80211_crypto_unregister.9 \
+       ieee80211_crypto.9 ieee80211_key_update_begin.9 \
+       ieee80211_crypto.9 ieee80211_key_update_end.9 \
+       ieee80211_crypto.9 ieee80211_notify_michael_failure.9 \
+       ieee80211_crypto.9 ieee80211_notify_replay_failure.9
+MLINKS+=ieee80211_input.9 ieee80211_input_all.9
+MLINKS+=ieee80211_node.9 ieee80211_dump_node.9 \
+       ieee80211_node.9 ieee80211_dump_nodes.9 \
        ieee80211_node.9 ieee80211_find_rxnode.9 \
-       ieee80211_node.9 ieee80211_find_txnode.9 \
+       ieee80211_node.9 ieee80211_find_rxnode_withkey.9 \
        ieee80211_node.9 ieee80211_free_node.9 \
        ieee80211_node.9 ieee80211_iterate_nodes.9 \
-       ieee80211_node.9 ieee80211_next_scan.9
-#      ieee80211_node.9 ieee80211_alloc_node.9 \
-#      ieee80211_node.9 ieee80211_dup_bss.9 \
-#      ieee80211_node.9 ieee80211_free_allnodes.9 \
-#      ieee80211_node.9 ieee80211_node_attach.9 \
-#      ieee80211_node.9 ieee80211_node_detach.9 \
-#      ieee80211_node.9 ieee80211_node_lateattach.9
-MLINKS+=ieee80211_output.9 ieee80211_add_rates.9 \
-       ieee80211_output.9 ieee80211_add_ssid.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_ref_node.9 \
+       ieee80211_node.9 ieee80211_unref_node.9
+MLINKS+=ieee80211_output.9 ieee80211_process_callback.9 \
+       ieee80211_output.9 M_SEQNO_GET.9 \
+       ieee80211_output.9 M_WME_GETAC.9
+MLINKS+=ieee80211_proto.9 ieee80211_new_state.9 \
+       ieee80211_proto.9 ieee80211_resume_all.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_wait_for_parent.9
+MLINKS+=ieee80211_radiotap.9 ieee80211_radiotap_active.9 \
+       ieee80211_radiotap.9 ieee80211_radiotap_active_vap.9 \
+       ieee80211_radiotap.9 ieee80211_radiotap_attach.9 \
+       ieee80211_radiotap.9 ieee80211_radiotap_tx.9 \
+       ieee80211_radiotap.9 radiotap.9
+MLINKS+=ieee80211_regdomain.9 ieee80211_alloc_countryie.9 \
+       ieee80211_regdomain.9 ieee80211_init_channels.9 \
+       ieee80211_regdomain.9 ieee80211_sort_channels.9
+MLINKS+=ieee80211_scan.9 ieee80211_add_scan.9 \
+       ieee80211_scan.9 ieee80211_bg_scan.9 \
+       ieee80211_scan.9 ieee80211_cancel_scan.9 \
+       ieee80211_scan.9 ieee80211_cancel_scan_any.9 \
+       ieee80211_scan.9 ieee80211_check_scan.9 \
+       ieee80211_scan.9 ieee80211_check_scan_current.9 \
+       ieee80211_scan.9 ieee80211_probe_curchan.9 \
+       ieee80211_scan.9 ieee80211_scan_assoc_fail.9 \
+       ieee80211_scan.9 ieee80211_scan_done.9 \
+       ieee80211_scan.9 ieee80211_scan_dump_channels.9 \
+       ieee80211_scan.9 ieee80211_scan_flush.9 \
+       ieee80211_scan.9 ieee80211_scan_iterate.9 \
+       ieee80211_scan.9 ieee80211_scanner_get.9 \
+       ieee80211_scan.9 ieee80211_scanner_register.9 \
+       ieee80211_scan.9 ieee80211_scanner_unregister.9 \
+       ieee80211_scan.9 ieee80211_scanner_unregister_all.9 \
+       ieee80211_scan.9 ieee80211_scan_next.9 \
+       ieee80211_scan.9 ieee80211_scan_timeout.9 \
+       ieee80211_scan.9 ieee80211_start_scan.9
+MLINKS+=ieee80211_vap.9 ieee80211_vap_attach.9 \
+       ieee80211_vap.9 ieee80211_vap_detach.9 \
+       ieee80211_vap.9 ieee80211_vap_setup.9
 MLINKS+=ifnet.9 ifaddr.9 \
        ifnet.9 if_data.9 \
        ifnet.9 ifqueue.9
index 3ae0545..aacaa07 100644 (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
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD$
-.\" $DragonFly: src/share/man/man9/ieee80211.9,v 1.4 2006/06/28 19:41:59 swildner Exp $
-.\" $Id: ieee80211.9,v 1.3 2004/07/07 12:59:39 ru Exp $
+.\" $FreeBSD: src/share/man/man9/ieee80211.9,v 1.7 2010/03/29 17:39:38 trasz Exp $
 .\"
-.Dd June 28, 2006
-.Dt IEEE80211 9
+.Dd April 28, 2010
+.Dt NET80211 9
 .Os
 .Sh NAME
-.Nm ieee80211_ifattach ,
-.Nm ieee80211_ifdetach ,
-.Nm ieee80211_mhz2ieee ,
-.Nm ieee80211_chan2ieee ,
-.Nm ieee80211_ieee2mhz ,
-.Nm ieee80211_media_init ,
-.Nm ieee80211_media_change ,
-.Nm ieee80211_media_status ,
-.Nm ieee80211_watchdog ,
-.Nm ieee80211_setmode ,
-.Nm ieee80211_chan2mode ,
-.Nm ieee80211_rate2media ,
-.Nm ieee80211_media2rate
-.Nd core 802.11 network stack functions
+.Nm net80211
+.Nd 802.11 network layer
 .Sh SYNOPSIS
 .In netproto/802_11/ieee80211_var.h
 .Ft void
-.Fn ieee80211_ifattach "struct ieee80211com *ic"
+.Fn ieee80211_ifattach "struct ieee80211com *ic" "const uint8_t macaddr[IEEE80211_ADDR_LEN]"
 .Ft void
 .Fn ieee80211_ifdetach "struct ieee80211com *ic"
-.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 ieee80211com *ic" "ifm_change_cb_t media_change"
-.Fa "ifm_stat_cb_t media_stat"
-.Fc
-.Ft int
-.Fn ieee80211_media_change "struct ifnet *ifp"
-.Ft void
-.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr"
-.Ft void
-.Fn ieee80211_watchdog "struct ieee80211com *ic"
-.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"
 .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
-.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;
-Various fields of the
-.Vt struct ieee80211com
-instance pointed to by
-.Fa ic
-must be initialized to tell
-.Nm ieee80211
-about its capabilities.
-This function performs Ethernet and BPF attachment (by calling
-.Fn ether_ifattach
-and
-.Fn bpfattach_dlt )
-on behalf of the caller.
-It also implements the
-.Xr ifmedia 4
-interface.
+.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
-.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
-.\"
-The
-.Fn ieee80211_mhz2ieee
-utility function converts the frequency
-.Fa freq
-(specified in MHz) to an IEEE 802.11 channel number.
+.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
-.Fa flags
-argument is a hint which specifies whether the frequency is in
-the 2GHz ISM band
-.Pq Dv IEEE80211_CHAN_2GHZ
-or the 5GHz band
-.Pq Dv IEEE80211_CHAN_5GHZ ;
-appropriate clipping of the result is then performed.
+.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
-.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.
+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
-.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 Dv IEEE80211_CHAN_2GHZ
-or the 5GHz band
-.Pq Dv 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
-.Xr ifmedia 4
-interface, for the driver
-.Fa ic .
-It must be called by the driver after calling
+.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
-and before calling most
-.Nm ieee80211
-functions.
+function.
+The driver is expected to allocate and setup any device-private
+data structures before passing control.
 The
-.Fa media_change
-and
-.Fa media_stat
-arguments specify helper functions which will be invoked by the
-.Xr ifmedia 4
-framework when the user changes or queries media options,
-using a command such as
-.Xr ifconfig 8 .
+.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
-.Fn ieee80211_media_status
-and
-.Fn ieee80211_media_change
-functions are device-independent handlers for
-.Xr ifmedia 4
-commands and are not intended to be called directly.
+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 ProbeRequest
+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
-.\"
-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,
-getting rid of inactive
-.Vt struct ieee80211_node
-instances,
-as well as timing out scans.
+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
+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_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.
+.Nm
+layer propagates a subset of these capabilities to each vap through
+the equivalent fields:
+.Vt iv_caps ,
+.Vt iv_cryptocaps ,
+and
+.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_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.
+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_rate2media
-function converts the bit rate
-.Fa rate
-(measured in units of 0.5Mbps) to an
-.Xr ifmedia 4
-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
-.Xr ifmedia 4
-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 ioctl 2 ,
+.\".Xr ndis 4 ,
+.Xr ieee80211_amrr 9 ,
+.Xr ieee80211_beacon 9 ,
+.Xr ieee80211_bmiss 9 ,
 .Xr ieee80211_crypto 9 ,
+.Xr ieee80211_ddb 9 ,
 .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 man page was written by
-.An Bruce M. Simpson Aq bms@FreeBSD.org
-and
-.An Darron Broad Aq darron@kewl.org .
+.Xr ieee80211_regdomain 9 ,
+.Xr ieee80211_scan 9 ,
+.Xr ieee80211_vap 9 ,
+.Xr ifnet 9 ,
+.Xr malloc 9
diff --git a/share/man/man9/ieee80211_amrr.9 b/share/man/man9/ieee80211_amrr.9
new file mode 100644 (file)
index 0000000..4153886
--- /dev/null
@@ -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: src/share/man/man9/ieee80211_amrr.9,v 1.2 2009/09/18 00:33:47 brueffer Exp $
+.\"
+.Dd April 28, 2010
+.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
diff --git a/share/man/man9/ieee80211_beacon.9 b/share/man/man9/ieee80211_beacon.9
new file mode 100644 (file)
index 0000000..08a0639
--- /dev/null
@@ -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: src/share/man/man9/ieee80211_beacon.9,v 1.2 2009/09/18 00:33:47 brueffer Exp $
+.\"
+.Dd April 28, 2010
+.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
diff --git a/share/man/man9/ieee80211_bmiss.9 b/share/man/man9/ieee80211_bmiss.9
new file mode 100644 (file)
index 0000000..33eec63
--- /dev/null
@@ -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: src/share/man/man9/ieee80211_bmiss.9,v 1.2 2009/09/18 00:33:47 brueffer Exp $
+.\"
+.Dd April 28, 2010
+.Dt IEEE80211_BMISS 9
+.Os
+.Sh NAME
+.Nm ieee80211_bmiss
+.Nd 802.11 beacon miss support
+.Sh SYNOPSIS
+.In net80211/ieee80211_var.h
+.Pp
+.Ft void
+.Fn ieee80211_beacon_miss "struct ieee80211com *"
+.Sh DESCRIPTION
+The
+.Nm net80211
+software layer provides a support framework for drivers that includes
+handling beacon miss events in station mode.
+Drivers can dispatch beacon miss events that are recognized in hardware or
+.Nm net80211
+can detect beacon miss if the driver dispatches received beacon frames
+through the normal receive path.
+Software beacon miss support is especially useful when multiple vaps
+are operating and any hardware beacon miss support is not available
+(e.g. operating as an access point together with one or more station
+mode vaps).
+.Pp
+Drivers should dispatch beacon miss events recognized in the driver with
+.Fn ieee80211_beacon_miss .
+This causes some number of ProbeRequest frames to be sent to the
+access point to check if the association is still alive.
+If no response is received and roaming mode is set to
+.Dv IEEE80211_ROAMING_AUTO
+then
+.Nm net80211
+will try to re-associate and if that fails
+trigger a scan to look for the access point or another suitable AP.
+When the
+.Nm net80211
+state machine is being operated manually, e.g. by
+.Xr wpa_supplicant 8 ,
+then applications are notified of the state change and are responsible
+for handling the work of scanning for a new access point.
+The number of beacon miss events (without a ProbeResponse) is user
+settable with the
+.Dv IEEE80211_IOC_BMISSTHRESHOLD
+request.
+.Pp
+Software beacon miss detection is enabled per-vap by setting the
+.Dv IEEE80211_FEXT_SWBMISS
+flag.
+Typically this is done when a vap is setup
+when the
+.Dv IEEE80211_CLONE_NOBEACONS
+option is supplied to the clone operation.
+But drivers may also force this when they know they need help detecting
+beacon miss.
+When beacon miss is detected in software the event is dispatched without
+driver involvement.
+Note that software beacon miss handling is not limited to station mode;
+it can be used in any operating mode where beacons from a peer station
+are received.
+.Sh SEE ALSO
+.Xr wpa_supplicant 8 ,
+.Xr ieee80211 9 ,
+.Xr ieee80211_vap 9
index 30fa461..3706f9f 100644 (file)
 .\"
-.\" Copyright (c) 2006 The DragonFly Project.  All rights reserved.
-.\" 
+.\" 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.
-.\" 3. Neither the name of The DragonFly Project nor the names of its
-.\"    contributors may be used to endorse or promote products derived
-.\"    from this software without specific, prior written permission.
-.\" 
-.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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
-.\" COPYRIGHT HOLDERS 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
+.\"    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.
 .\"
-.\" $DragonFly: src/share/man/man9/ieee80211_crypto.9,v 1.3 2006/06/28 19:41:59 swildner Exp $
+.\" $FreeBSD: src/share/man/man9/ieee80211_crypto.9,v 1.6 2010/03/29 17:39:38 trasz Exp $
+.\" $Id: ieee80211_crypto.9,v 1.3 2004/03/04 10:42:56 bruce Exp $
 .\"
-.Dd June 28, 2006
+.Dd April 28, 2010
 .Dt IEEE80211_CRYPTO 9
 .Os
 .Sh NAME
-.Nm ieee80211_crypto_encap
-.Nd 802.11 encryption function
+.Nm ieee80211_crypto
+.Nd 802.11 cryptographic support
 .Sh SYNOPSIS
-.In netproto/802_11/ieee80211_var.h
+.In net80211/ieee80211_var.h
+.\"
+.Pp
+.Ft void
+.Fn ieee80211_crypto_register "const struct ieee80211_cipher *"
+.\"
+.Ft void
+.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 *
-.Fo ieee80211_crypto_encap
-.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "struct mbuf *m"
+.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
-This function provides 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
-.\"
+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 ieee80211_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_encap
-function runs the appropriate encryption algorithm over the 802.11
-encapsulated frame held in the mbuf chain
-.Fa m ,
-for transmission on the interface
-.Fa ic .
+.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
-.Fa ni
-argument specifies the target to which the encrypted frame will be transmitted.
-It must not be
-.Dv NULL ,
-and is typically the return value of
-.Xr ieee80211_find_txnode 9 .
-.\"
-.Sh IMPLEMENTATION NOTES
-The key used to encrypt unicast frames is stored in
-.Fa ni .
-.\"
-.Sh RETURN VALUES
-If successful,
-the key used to encrypt the frame is returned.
-Otherwise,
-.Dv NULL
-is returned.
-.\"
+.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
+.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 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 man page was written by
-.An Sepherosa Ziehau
-and
-.An Sascha Wildner .
+.Xr ioctl 2 ,
+.Xr wlan_ccmp 4 ,
+.Xr wlan_tkip 4 ,
+.Xr wlan_wep 4
similarity index 51%
copy from share/man/man9/ieee80211_proto.9
copy to share/man/man9/ieee80211_ddb.9
index f238571..3dff41f 100644 (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
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD$
-.\" $DragonFly: src/share/man/man9/ieee80211_proto.9,v 1.3 2006/06/28 19:41:59 swildner Exp $
-.\" $Id: ieee80211_proto.9,v 1.2 2004/07/07 12:59:39 ru Exp $
+.\" $FreeBSD: src/share/man/man9/ieee80211_ddb.9,v 1.2 2009/09/18 00:33:47 brueffer Exp $
 .\"
-.Dd June 25, 2006
-.Dt IEEE80211_PROTO 9
+.Dd April 28, 2010
+.Dt IEEE80211_DDB 9
 .Os
 .Sh NAME
-.Nm ieee80211_proto_attach ,
-.Nm ieee80211_proto_detach ,
-.Nm ieee80211_print_essid ,
-.Nm ieee80211_dump_pkt ,
-.Nm ieee80211_fix_rate
-.Nd software 802.11 stack protocol helper functions
+.Nm ieee80211_ddb
+.Nd 802.11 ddb support
 .Sh SYNOPSIS
-.In netproto/802_11/ieee80211_var.h
-.In netproto/802_11/ieee80211_proto.h
-.Ft void
-.Fn ieee80211_proto_attach "struct ieee80211com *ic"
-.Ft void
-.Fn ieee80211_proto_detach "struct ieee80211com *ic"
-.Ft void
-.Fn ieee80211_print_essid "const uint8_t *essid" "int len"
-.Ft void
-.Fn ieee80211_dump_pkt "const uint8_t *buf" "int len" "int rate" "int rssi"
-.Ft int
-.Fo ieee80211_fix_rate
-.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int flags"
-.Fc
+.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
-.\" XXX
-These
-functions are helper functions used throughout the software 802.11 protocol
-stack.
-.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 man page was written by
-.An Bruce M. Simpson Aq bms@FreeBSD.org
+.Nm net80211
+layer includes
+.Xr ddb 4
+support for displaying important data structures.
+This is especially important because wireless applications are often
+built for embedded environments where cross-machine or post-mortem
+debugging facilities like
+.Xr kgdb 1
+are infeasible.
+.Pp
+The most commonly used command is
+.Bd -literal -offset indent
+show all vaps/a
+.Ed
+.Pp
+which dumps the contents of all
+.Vt ieee80211vap ,
+.Vt ieee80211com ,
 and
-.An Darron Broad Aq darron@kewl.org .
+.Vt ieee80211_node
+data structures in the system.
+.Sh SEE ALSO
+.Xr ddb 4 ,
+.Xr ieee80211 9
index 3b89efc..32c1619 100644 (file)
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD$
-.\" $DragonFly: src/share/man/man9/ieee80211_input.9,v 1.4 2006/06/28 19:41:59 swildner Exp $
-.\" $Id: ieee80211_input.9,v 1.2 2004/07/07 12:59:39 ru Exp $
+.\" $FreeBSD: src/share/man/man9/ieee80211_input.9,v 1.5 2009/09/18 00:33:47 brueffer Exp $
 .\"
-.Dd June 28, 2006
+.Dd April 28, 2010
 .Dt IEEE80211_INPUT 9
 .Os
 .Sh NAME
-.Nm ieee80211_input ,
-.Nm ieee80211_recv_mgmt
+.Nm ieee80211_input
 .Nd software 802.11 stack input functions
 .Sh SYNOPSIS
-.In netproto/802_11/ieee80211_var.h
+.In net80211/ieee80211_var.h
 .Ft void
 .Fo ieee80211_input
-.Fa "struct ieee80211com *ic" "struct mbuf *m" "struct ieee80211_node *ni"
-.Fa "int rssi" "uint32_t rstamp"
+.Fa "struct ieee80211_node *"
+.Fa "struct mbuf *"
+.Fa "int rssi"
+.Fa "int noise"
 .Fc
 .Ft void
-.Fo ieee80211_recv_mgmt
-.Fa "struct ieee80211com *ic" "struct mbuf *m" "struct ieee80211_node *ni"
-.Fa "int subtype" "int rssi" "uint32_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 interface
-.Fa ic
-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, and must not be
-.Dv NULL .
-Typically,
-.Fa ni
-is the return value of
-.Xr ieee80211_find_rxnode 9 .
-The arguments
-.Fa rssi
 and
-.Fa rstamp
-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 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
-through
-.Va ic_recv_mgmt .
-If the driver wants to intercept the 802.11 management frames' processing,
-it will save
-.Va ic_recv_mgmt
-for later use and assign its own
-.Fn recv_mgmt
-to
-.Va ic_recv_mgmt .
-The saved function,
-i.e.
-.Fn ieee80211_recv_mgmt ,
-must be called within the driver's own
-.Fn recv_mgmt .
-.\"
-.Sh SEE ALSO
-.Xr ieee80211 9 ,
-.Xr ifnet 9
-.Sh HISTORY
+.Vt rssi
+parameter is the Receive Signal Strength Indication of the frame
+measured in 0.5dBm units relative to the noise floor.
 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 man page was written by
-.An Bruce M. Simpson Aq bms@FreeBSD.org
-and
-.An Darron Broad Aq darron@kewl.org .
+.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
index eb9090e..725f8b2 100644 (file)
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD$
-.\" $DragonFly: src/share/man/man9/ieee80211_node.9,v 1.5 2007/05/17 08:19:02 swildner Exp $
-.\" $Id: ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $
+.\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.7 2010/03/29 17:39:38 trasz Exp $
 .\"
-.Dd June 28, 2006
+.Dd April 28, 2010
 .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_create_ibss ,
-.Nm ieee80211_next_scan ,
-.Nm ieee80211_end_scan ,
-.\" .Nm ieee80211_alloc_node ,
-.\" .Nm ieee80211_dup_bss ,
-.Nm ieee80211_find_txnode ,
-.Nm ieee80211_find_rxnode ,
-.Nm ieee80211_find_node ,
-.Nm ieee80211_free_node ,
-.\" .Nm ieee80211_free_allnodes ,
-.Nm ieee80211_iterate_nodes
+.Nm ieee80211_node
 .Nd software 802.11 stack node management functions
 .Sh SYNOPSIS
-.In netproto/802_11/ieee80211_var.h
-.In netproto/802_11/ieee80211_proto.h
-.In netproto/802_11/ieee80211_node.h
-.\" .Ft void
-.\" .Fn ieee80211_node_attach "struct ieee80211com *ic"
-.\" .Ft void
-.\" .Fn ieee80211_node_lateattach "struct ieee80211com *ic"
-.\" .Ft void
-.\" .Fn ieee80211_node_detach "struct ieee80211com *ic"
-.Ft void
-.Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset"
-.Ft void
-.Fo ieee80211_create_ibss
-.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
-.Fc
-.Ft int
-.Fn ieee80211_next_scan "struct ieee80211com *ic"
-.Ft void
-.Fn ieee80211_end_scan "struct ieee80211com *ic"
-.\" .Ft struct ieee80211_node *
-.\" .Fo ieee80211_alloc_node
-.\" .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
-.\" .Fc
-.\" .Ft struct ieee80211_node *
-.\" .Fo ieee80211_dup_bss
-.\" .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
-.\" .Fc
-.Ft struct ieee80211_node *
-.Fn ieee80211_find_txnode "struct ieee80211com *ic" "const uint8_t *macaddr"
+.In net80211/ieee80211_var.h
+.\"
 .Ft struct ieee80211_node *
 .Fo ieee80211_find_rxnode
-.Fa "struct ieee80211com *ic" "const struct ieee80211_frame_min *wh"
+.Fa "struct ieee80211com *"
+.Fa "const struct ieee80211_frame_min *"
 .Fc
+.\"
 .Ft struct ieee80211_node *
-.Fo ieee80211_find_node
-.Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
+.Fo ieee80211_find_rxnode_withkey
+.Fa "struct ieee80211com *"
+.Fa "const struct ieee80211_frame_min *"
+.Fa "ieee80211_keyix"
 .Fc
-.Ft void
-.Fn ieee80211_free_node "struct ieee80211_node *ni"
-.\" .Ft void
-.\" .Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt"
-.Ft void
-.Fo ieee80211_iterate_nodes
-.Fa "struct ieee80211_node_table *nt" "ieee80211_iter_func *f" "void *arg"
-.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,
-implementing transmission rate control algorithms,
-or providing signal quality information about neighbouring nodes.
-.Pp
-.\"
-.\" The
-.\" .Fn ieee80211_node_attach
-.\" function is called from
-.\" .Xr ieee80211_ifattach 9
-.\" to initialize node databases management callbacks and control variables
-.\" for the interface
-.\" .Fa ic
-.\" (specifically for memory allocation,
-.\" node copying,
-.\" node signal inspection, and station inactivity timer).
-.\" .Pp
-.\"
-.\" The
-.\" .Fn ieee80211_node_lateattach
-.\" function initialises the
-.\" node databases,
-.\" crypto and authentication settings of
-.\" .Va ic_bss
-.\" associated with the interface
-.\" .Fa ic
-.\" during
-.\" .Xr ieee80211_media_init 9 .
-.\" .Pp
 .\"
-.\" The
-.\" .Fn ieee80211_node_detach
-.\" function destroys all node databases associated with the interface
-.\" .Fa ic .
-.\" .Pp
-.\"
-The
-.Fn ieee80211_begin_scan
-function initialises the node databases in preparation of an active
-scan for an access point on the interface
-.Fa ic .
-The scan begins on the next radio channel by calling
-.Fn ieee80211_next_scan
-internally.
-If
-.Fa reset
-is non-zero, the interface
-.Fa ic Ap s
-node table
-.Va ic_scan ,
-which holds previously detected access points,
-will be cleared.
-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_create_ibss
-function sets up the net80211-specific portion of an interface's softc
-.Fa ic ,
-for use in IBSS mode or HOSTAP mode.
-.Pp
-.\"
-The
-.Fn ieee80211_next_scan
-function is used to inform the
-.Xr ieee80211 9
-layer that the interface
-.Fa ic
-is now scanning for an access point on the next radio channel.
-.\" XXX should call ieee80211_new_state(ic, IEEE80211_S_SCAN)
-.\" XXX we may need a manpage to describe ieee80211_new_state()
-.\" 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_end_scan
-function is called by
-.Fn ieee80211_next_scan
-when the state machine has performed a full cycle of scanning on
-all available radio channels.
-Internally,
-.Fn ieee80211_end_scan
-will inspect the node table
-.Va ic_scan
-of the interface
-.Fa ic
-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
+.Ft struct ieee80211_node *
+.Fn ieee80211_ref_node "struct ieee80211_node *"
 .\"
-.\" 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 node table
-.\" .Fa nt .
-.\" If the allocation is successful, the node structure is initialised by
-.\" .Fn ieee80211_setup_node ;
-.\" otherwise,
-.\" .Dv NULL
-.\" is returned.
-.\" .Pp
+.Ft void
+.Fn ieee80211_unref_node "struct ieee80211_node *"
 .\"
-.\" 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 node table
-.\" .Fa nt .
-.\" If the allocation is successful, the node structure is initialised by
-.\" .Fn ieee80211_setup_node ;
-.\" otherwise,
-.\" .Dv NULL
-.\" is returned.
-.\" .Pp
+.Ft void
+.Fn ieee80211_free_node "struct ieee80211_node *"
 .\"
-The
-.Fn ieee80211_find_txnode
-function will locate a suitable node entry for a frame to be delivered to
-.Fa macaddr
-through the interface
-.Fa ic .
-.Pp
+.Ft void
+.Fo ieee80211_iterate_nodes
+.Fa "struct ieee80211_node_table *"
+.Fa "ieee80211_iter_func *f"
+.Fa "void *arg"
+.Fc
 .\"
-The
-.Fn ieee80211_find_rxnode
-function will find the node entry which represents the sender of
-.Fa wh ,
-which is received on the interface
-.Fa ic .
-.Pp
+.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
 The
-.Fn ieee80211_find_node
-function will iterate through the node table
-.Fa nt ,
-searching for a node entry which matches
-.Fa macaddr .
+.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
-.\"
-If
-.Fn ieee80211_find_txnode ,
-.Fn ieee80211_find_rxnode ,
-or
-.Fn ieee80211_find_node ,
-returns a non-NULL node entry,
-the node entry's reference count is incremented,
-so the caller of these functions is responsible to call
-.Fn ieee80211_free_node .
-.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_ref_node
+and
+.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
-function will decrement the reference count of the node
-.Fa ni .
-If either the reference count drops to zero or
-the last reference left is from
-.Va nt_keyixmap
-then
-.Fa ni
-will be removed from the node table where it resides,
-and any memory associated with the node will be freed.
+to release a reference and, if the count goes to zero, reclaim the
+table entry.
 .Pp
-.\"
-.\" The
-.\" .Fn ieee80211_free_allnodes
-.\" function will iterate through the node table
-.\" .Fa nt ,
-.\" either calling
-.\" .Fn ieee80211_free_node
-.\" for all nodes that reside in
-.\" .Fa nt
-.\" or just remove them from
-.\" .Fa nt .
-.\" .Pp
-.\"
-The
+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
-function will call the user-defined callback function
-.Fa f
-for all nodes in the node table
-.Fa nt .
-The callback is invoked with the user-supplied value
-.Fa arg
-and a pointer to the current node.
-.\"
-.Sh RETURN VALUES
-The function
-.Fn ieee80211_next_scan
-returns 0,
-if a full cycle of scanning on all available radio channels is done.
-Otherwise, 1 is returned.
+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
-.\"
-The function
-.Fn ieee80211_find_txnode
-returns a node entry that is suitable to be used to send a frame to
-.Fa macaddr .
-If there is no suitable node found,
-.Dv NULL
-is returned.
+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
-.\"
-The function
-.Fn ieee80211_find_rxnode
-returns a node entry that represents the sender of
-.Fa wh .
-If no suitable node entry can be found,
-.Va ic_bss
-is returned.
+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
-.\"
-The function
-.Fn ieee80211_find_node
-returns a pointer to the node entry which matches
-.Fa macaddr .
-If no match is found,
-.Dv NULL
-is returned.
-.\"
+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 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 man page was written by
-.An Bruce M. Simpson Aq bms@FreeBSD.org
-and
-.An Darron Broad Aq darron@kewl.org .
+.Xr ieee80211_proto 9
index 1feff24..10bc60c 100644 (file)
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD$
-.\" $DragonFly: src/share/man/man9/ieee80211_output.9,v 1.7 2007/04/09 21:20:37 swildner Exp $
-.\" $Id: ieee80211_output.9,v 1.2 2004/07/07 12:59:39 ru Exp $
+.\" $FreeBSD: src/share/man/man9/ieee80211_output.9,v 1.6 2010/03/29 17:39:38 trasz Exp $
+.\" $Id: ieee80211_output.9,v 1.5 2004/03/04 12:31:18 bruce Exp $
 .\"
-.Dd June 28, 2006
+.Dd April 28, 2010
 .Dt IEEE80211_OUTPUT 9
 .Os
 .Sh NAME
-.Nm ieee80211_encap ,
-.Nm ieee80211_send_mgmt ,
-.Nm ieee80211_add_ssid ,
-.Nm ieee80211_add_rates ,
-.Nm ieee80211_add_xrates
+.Nm ieee80211_output
 .Nd software 802.11 stack output functions
 .Sh SYNOPSIS
-.In netproto/802_11/ieee80211_var.h
-.In netproto/802_11/ieee80211_proto.h
-.Ft struct mbuf *
-.Fo ieee80211_encap
-.Fa "struct ieee80211com *ic" "struct mbuf *m" "struct ieee80211_node *ni"
-.Fc
+.In net80211/ieee80211_var.h
+.\"
 .Ft int
-.Fo ieee80211_send_mgmt
-.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int type" "int arg"
-.Fc
-.Ft uint8_t *
-.Fn ieee80211_add_ssid "uint8_t *frm" "const uint8_t *ssid" "int ssid_len"
-.Ft uint8_t *
-.Fn ieee80211_add_rates "uint8_t *frm" "const struct ieee80211_rateset *rs"
-.Ft uint8_t *
-.Fn ieee80211_add_xrates "uint8_t *frm" "const struct ieee80211_rateset *rs"
-.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 ic .
-The argument
-.Fa ni
-is a reference to the destination node.
-.Pp
+.Fn M_WME_GETAC "struct mbuf *"
 .\"
-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 .
-The node entry
-.Fa ni
-must not be
-.Dv NULL
-and is typically the non-NULL return value of
-.Xr ieee80211_find_txnode 9 .
-This function is typically called through
-.Fn IEEE80211_SEND_MGMT ,
-which is a wrapper for the invocation of
-.Va ic_send_mgmt .
-.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
-The destination node
-.Fa ni
-will have its reference count incremented to reflect its use for an
-indeterminate amount of time.
-This reference is freed either in
-.Va if_start
-or,
-during the interrupt service routine for transmission completing
-if certain transmission rate control algorithms are used.
-.Pp
+.Ft int
+.Fn M_SEQNO_GET "struct mbuf *"
 .\"
-The
-.Fn ieee80211_add_ssid
-utility function is used to add the service set ID element
-.Fa ssid
-to the frame
-.Fa frm .
-The
-.Fa ssid_len
-argument indicates the length of the
-.Fa ssid
-to be added.
-.Pp
+.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
 The
-.Fn ieee80211_add_rates
-utility function is used to add the rate set element
-.Fa rs
-to the frame
-.Fa frm .
+.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
-.\"
-The
-.Fn ieee80211_add_xrates
-utility function is used to add the extended rate set element
-.Fa rs
-to the frame
-.Fa frm .
+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
-.\"
-The functions
-.Fn ieee80211_add_ssid ,
-.Fn ieee80211_add_rates
-and
-.Fn ieee80211_add_xrates
-are typically used when constructing management frames from within the
-software 802.11 stack in 802.11g mode.
-.\"
-.Sh RETURN VALUES
-If the function
-.Fn ieee80211_encap
-is successful,
-the mbuf chain
-.Fa m
-is updated with the 802.11 frame header prepended,
-and a pointer to the head of the updated mbuf chain is returned.
-If an error occurs,
-.Dv NULL
-will be returned,
-and
-.Fa m
-will be freed.
+.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 with
+.Dq full power .
 .Pp
-.\"
-The function
-.Fn ieee80211_send_mgmt
-returns 0 if successful;
-if temporary buffer space is not available,
-it returns
-.Er ENOMEM .
+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
-.\"
-The functions
-.Fn ieee80211_add_ssid ,
-.Fn ieee80211_add_rates
+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
+.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
-.Fn ieee80211_add_xrates
-return a pointer to the location in the
-.Fa frm
-after the addition of the second argument.
-.\"
+.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 man page was written by
-.An Bruce M. Simpson Aq bms@FreeBSD.org
-and
-.An Darron Broad Aq darron@kewl.org .
index f238571..de21927 100644 (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
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD$
-.\" $DragonFly: src/share/man/man9/ieee80211_proto.9,v 1.3 2006/06/28 19:41:59 swildner Exp $
-.\" $Id: ieee80211_proto.9,v 1.2 2004/07/07 12:59:39 ru Exp $
+.\" $FreeBSD: src/share/man/man9/ieee80211_proto.9,v 1.5 2009/09/18 00:33:47 brueffer Exp $
 .\"
-.Dd June 25, 2006
+.Dd April 28, 2010
 .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
-.Nd software 802.11 stack protocol helper functions
+.Nm ieee80211_proto
+.Nd 802.11 state machine support
 .Sh SYNOPSIS
-.In netproto/802_11/ieee80211_var.h
-.In netproto/802_11/ieee80211_proto.h
+.In net80211/ieee80211_var.h
+.Pp
 .Ft void
-.Fn ieee80211_proto_attach "struct ieee80211com *ic"
+.Fn ieee80211_start_all "struct ieee80211com *"
 .Ft void
-.Fn ieee80211_proto_detach "struct ieee80211com *ic"
+.Fn ieee80211_stop_all "struct ieee80211com *"
 .Ft void
-.Fn ieee80211_print_essid "const uint8_t *essid" "int len"
+.Fn ieee80211_suspend_all "struct ieee80211com *"
 .Ft void
-.Fn ieee80211_dump_pkt "const uint8_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
-.\" XXX
-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 Announcement (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 wpa_supplicant 8 ,
 .Xr ieee80211 9 ,
-.Xr ifnet 9
+.Xr ifnet 9 ,
+.Xr taskqueue 9
 .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 man page was written by
-.An Bruce M. Simpson Aq bms@FreeBSD.org
-and
-.An Darron Broad Aq darron@kewl.org .
index 310d95e..c0a194c 100644 (file)
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\" $FreeBSD: src/share/man/man9/ieee80211_radiotap.9,v 1.3 2004/07/07 12:59:39 ru Exp $
-.\" $NetBSD: ieee80211_radiotap.9,v 1.9 2006/03/12 03:22:02 dyoung Exp $
-.\" $DragonFly: src/share/man/man9/ieee80211_radiotap.9,v 1.7 2007/11/23 23:03:57 swildner Exp $
+.\" $FreeBSD: src/share/man/man9/ieee80211_radiotap.9,v 1.7 2009/09/18 00:33:47 brueffer Exp $
 .\"
-.Dd December 25, 2006
+.Dd April 28, 2010
 .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 net/bpf.h
-.In netproto/802_11/ieee80211_var.h
-.In netproto/802_11/ieee80211_ioctl.h
-.In netproto/802_11/ieee80211_radiotap.h
+.In net80211/ieee80211_var.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.
-.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.
+.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
-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.
-.Pp
-The capture fields were packed into the header as compactly as possible,
-modulo the requirements that they had to be packed swiftly,
-with their natural alignment,
-in the same order as the bits indicating their presence.
-.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 {
-       uint8_t         it_version;     /* set to 0 */
-       uint8_t         it_pad;
-       uint16_t        it_len;         /* entire length */
-       uint32_t        it_present;     /* fields present */
-} __packed;
-.Ed
-.Pp
-.\"
-A device driver implementing
+A
+.Nm net80211
+device driver supporting
 .Vt radiotap
-typically defines a structure embedding an instance of
-.Vt "struct ieee80211_radiotap_header"
-at the beginning,
-with subsequent fields naturally aligned,
-and in the appropriate order.  Also, a driver defines
-a macro to set the bits of the
+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
-Radiotap capture fields are in little-endian byte order.
-.Pp
-Radiotap capture fields
-.Em must be naturally aligned .
-That is, 16-, 32-, and 64-bit fields must begin on 16-, 32-, and
-64-bit boundaries, respectively.
-In this way, drivers can avoid unaligned accesses to radiotap
-capture fields.
-radiotap-compliant drivers must insert padding before a capture
-field to ensure its natural alignment.
-radiotap-compliant packet dissectors, such as
-.Xr tcpdump 1 ,
-expect the padding.
+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
-Developers beware: all compilers may not pack structs alike.
-If a driver developer constructs their radiotap header with a packed
-structure, in order to ensure natural alignment, then it is important
-that they insert padding bytes by themselves.
+.Bd -literal -offset indent
+if (ieee80211_radiotap_active_vap(vap)) {
+       ... /* record transmit state */
+       ieee80211_radiotap_tx(vap, m); /* capture transmit event */
+}
+.Ed
 .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 bpfattach_dlt
-with the data-link type set to
-.Dv DLT_IEEE802_11_RADIO .
+While in the receive path capture is handled in
+.Nm net80211
+but state must be captured before dispatching a frame:
 .Pp
-.\"
-When 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_ptap
-function.
+.Bd -literal -offset indent
+if (ieee80211_radiotap_active(ic)) {
+       ... /* record receive state */
+}
+\&...
+ieee80211_input(...);  /* packet capture handled in net80211 */
+.Ed
 .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 netproto/802_11/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.
-A driver sets
-.Dv IEEE80211_RADIOTAP_EXT
-to extend the it_present bitmap
-by another 64 bits.
-The bitmap can be extended by multiples of 32 bits to 96, 128, 160
-bits or longer, by setting
-.Dv IEEE80211_RADIOTAP_EXT
-in the extensions.
-The bitmap ends at the first extension field where
-.Dv IEEE80211_RADIOTAP_EXT
-is not set.
+.It Dv IEEE80211_RADIOTAP_XCHANNEL
+This field contains four values: a 32-bit unsigned bitmap of
+flags that describe the channel attributes, a 16-bit unsigned
+frequency 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 frequency and IEEE channel number.
 .El
 .Sh EXAMPLES
-Radiotap header for the Intel(R) PRO/Wireless 2200BG/2225BG/2915ABG driver
+Radiotap receive definitions for the Intersil Prism driver:
 .Bd -literal -offset indent
-struct iwi_rx_radiotap_header {
-       struct ieee80211_radiotap_header wr_ihdr;
-       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_antenna;
-};
+#define WI_RX_RADIOTAP_PRESENT \\
+        ((1 << IEEE80211_RADIOTAP_TSFT) \\
+         (1 << IEEE80211_RADIOTAP_FLAGS) | \\
+         (1 << IEEE80211_RADIOTAP_RATE) | \\
+         (1 << IEEE80211_RADIOTAP_CHANNEL) | \\
+         (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
-Bitmap indicating which fields are present in the above structure:
+and transmit definitions for the Atheros driver:
 .Bd -literal -offset indent
-#define IWI_RX_RADIOTAP_PRESENT \\
-       ((1 << IEEE80211_RADIOTAP_FLAGS) | \\
-        (1 << IEEE80211_RADIOTAP_RATE) | \\
-        (1 << IEEE80211_RADIOTAP_CHANNEL) | \\
-        (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \\
-        (1 << IEEE80211_RADIOTAP_ANTENNA))
+#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 .
-.An David Young
-is the maintainer of the radiotap capture format.
-Contact him to add new capture fields.
-.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 .
diff --git a/share/man/man9/ieee80211_regdomain.9 b/share/man/man9/ieee80211_regdomain.9
new file mode 100644 (file)
index 0000000..a5a5bcd
--- /dev/null
@@ -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: src/share/man/man9/ieee80211_regdomain.9,v 1.2 2009/09/18 00:33:47 brueffer Exp $
+.\"
+.Dd April 28, 2010
+.Dt IEEE80211_REGDOMAIN 9
+.Os
+.Sh NAME
+.Nm ieee80211_regdomain
+.Nd 802.11 regulatory support
+.Sh SYNOPSIS
+.In net80211/ieee80211_var.h
+.In net80211/ieee80211_regdomain.h
+.Pp
+.Ft int
+.Fo ieee80211_init_channels
+.Fa "struct ieee80211com *"
+.Fa "const struct ieee80211_regdomain *"
+.Fa "const uint8_t bands[]"
+.Fc
+.\"
+.Ft void
+.Fo ieee80211_sort_channels
+.Fa "struct ieee80211_channel *"
+.Fa "int nchans"
+.Fc
+.\"
+.Ft "struct ieee80211_appie *"
+.Fn ieee80211_alloc_countryie "struct ieee80211com *"
+.Sh DESCRIPTION
+The
+.Nm net80211
+software layer provides a support framework for drivers that includes
+comprehensive regulatory support.
+.Nm net80211
+provides mechanisms that enforce
+.Em "regulatory policy"
+by privileged user applications.
+.Pp
+Drivers define a device's capabilities and can
+intercept and control regulatory changes requested through
+.Nm net80211 .
+The initial regulatory state, including the channel list, must be
+filled in by the driver before calling
+.Fn ieee80211_ifattach .
+The channel list should reflect the set of channels the device is
+.Em calibrated
+for use on.
+This list may also be requested later through the
+.Vt ic_getradiocaps
+method in the
+.Vt ieee80211com
+structure.
+The
+.Fn ieee80211_init_channels
+function is provided as a rudimentary fallback for drivers that do not
+(or cannot) fill in a proper channel list.
+Default regulatory state is supplied such as the regulatory SKU,
+ISO country code, location (e.g. indoor, outdoor), and a set of
+frequency bands the device is capable of operating on.
+.Nm net80211
+populates the channel table in
+.Vt ic_channels
+with a default set of channels and capabilities.
+Note this mechanism should be used with care as any mismatch between
+the channel list created and the device's capabilities can result
+in runtime errors (e.g. a request to operate on a channel the device
+does not support).
+The SKU and country information are used for generating 802.11h protocol
+elements and related operation such as for 802.11d; mis-setup by a
+driver is not fatal, only potentially confusing.
+.Pp
+Devices that do not have a fixed/default regulatory state can set
+the regulatory SKU to
+.Dv SKU_DEBUG
+and country code to
+.Dv CTRY_DEFAULT
+and leave proper setup to user applications.
+If default settings are known they can be installed and/or an event
+can be dispatched to user space using
+.Fn ieee80211_notify_country
+so that
+.Xr devd 8
+will do the appropriate setup work at system boot (or device insertion).
+.Pp
+The channel table is sorted to optimize lookups using the
+.Fn ieee80211_sort_channels
+routine.
+This should be done whenever the channel table contents are modified.
+.Pp
+The
+.Fn ieee80211_alloc_countryie
+function allocates an information element as specified by 802.11h.
+Because this is expensive to generate it is cached in
+.Vt ic_countryie
+and generated only when regulatory state changes.
+Drivers that call
+.Fn ieee80211_alloc_countryie
+directly should not help with this caching; doing so may confuse the
+.Nm net80211
+layer.
+.Sh DRIVER REGULATORY CONTROL
+Drivers can control regulatory change requests by overriding the
+.Vt ic_setregdomain
+method that checks change requests.
+While drivers can reject any request that does not meet its requirements
+it is recommended that one be lenient in what is accepted and, whenever
+possible, instead of rejecting a request, alter it to be correct.
+For example, if the transmit power cap for a channel is too high the
+driver can either reject the request or (better) reduce the cap to be
+compliant.
+Requests that include unacceptable channels should cause the request
+to be rejected as otherwise a mismatch may be created between application
+state and the state managed by
+.Nm net80211 .
+The exact rules by which to operate are still being codified.
+.Sh SEE ALSO
+.Xr regdomain 5 ,
+.Xr ifconfig 8 ,
+.Xr ieee80211 9
diff --git a/share/man/man9/ieee80211_scan.9 b/share/man/man9/ieee80211_scan.9
new file mode 100644 (file)
index 0000000..0141afb
--- /dev/null
@@ -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: src/share/man/man9/ieee80211_scan.9,v 1.4 2010/03/29 17:39:38 trasz Exp $
+.\"
+.Dd April 28, 2010
+.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.
+Only one vap at a time may be scanning; this scheduling policy
+is handled 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
diff --git a/share/man/man9/ieee80211_vap.9 b/share/man/man9/ieee80211_vap.9
new file mode 100644 (file)
index 0000000..6d88fbf
--- /dev/null
@@ -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: src/share/man/man9/ieee80211_vap.9,v 1.2 2009/09/18 00:33:47 brueffer Exp $
+.\"
+.Dd April 28, 2010
+.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