From 05ac2d0d30be792e7f2f4ef6d7bd5c57f08ffc8d Mon Sep 17 00:00:00 2001 From: Sascha Wildner Date: Wed, 28 Apr 2010 14:47:13 +0200 Subject: [PATCH] Sync our ieee80211*(9) manual pages with FreeBSD. --- Makefile_upgrade.inc | 58 ++ share/man/man9/Makefile | 119 ++- share/man/man9/ieee80211.9 | 725 +++++++++++++----- share/man/man9/ieee80211_amrr.9 | 194 +++++ share/man/man9/ieee80211_beacon.9 | 115 +++ share/man/man9/ieee80211_bmiss.9 | 91 +++ share/man/man9/ieee80211_crypto.9 | 307 ++++++-- .../{ieee80211_proto.9 => ieee80211_ddb.9} | 86 +-- share/man/man9/ieee80211_input.9 | 143 ++-- share/man/man9/ieee80211_node.9 | 493 +++++------- share/man/man9/ieee80211_output.9 | 299 ++++---- share/man/man9/ieee80211_proto.9 | 237 +++++- share/man/man9/ieee80211_radiotap.9 | 388 +++++----- share/man/man9/ieee80211_regdomain.9 | 143 ++++ share/man/man9/ieee80211_scan.9 | 350 +++++++++ share/man/man9/ieee80211_vap.9 | 154 ++++ 16 files changed, 2808 insertions(+), 1094 deletions(-) create mode 100644 share/man/man9/ieee80211_amrr.9 create mode 100644 share/man/man9/ieee80211_beacon.9 create mode 100644 share/man/man9/ieee80211_bmiss.9 copy share/man/man9/{ieee80211_proto.9 => ieee80211_ddb.9} (51%) create mode 100644 share/man/man9/ieee80211_regdomain.9 create mode 100644 share/man/man9/ieee80211_scan.9 create mode 100644 share/man/man9/ieee80211_vap.9 diff --git a/Makefile_upgrade.inc b/Makefile_upgrade.inc index 62f5d470c2..a2107c32dd 100644 --- a/Makefile_upgrade.inc +++ b/Makefile_upgrade.inc @@ -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 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index a80f7f4499..76e81a2282 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -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 diff --git a/share/man/man9/ieee80211.9 b/share/man/man9/ieee80211.9 index 3ae054531c..aacaa071b5 100644 --- a/share/man/man9/ieee80211.9 +++ b/share/man/man9/ieee80211.9 @@ -1,6 +1,5 @@ .\" -.\" Copyright (c) 2004 Bruce M. Simpson -.\" Copyright (c) 2004 Darron Broad +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -24,246 +23,546 @@ .\" 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 index 0000000000..41538868ab --- /dev/null +++ b/share/man/man9/ieee80211_amrr.9 @@ -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 index 0000000000..08a0639b8e --- /dev/null +++ b/share/man/man9/ieee80211_beacon.9 @@ -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 index 0000000000..33eec637d3 --- /dev/null +++ b/share/man/man9/ieee80211_bmiss.9 @@ -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 diff --git a/share/man/man9/ieee80211_crypto.9 b/share/man/man9/ieee80211_crypto.9 index 30fa4614e1..3706f9f48b 100644 --- a/share/man/man9/ieee80211_crypto.9 +++ b/share/man/man9/ieee80211_crypto.9 @@ -1,91 +1,260 @@ .\" -.\" Copyright (c) 2006 The DragonFly Project. All rights reserved. -.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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 diff --git a/share/man/man9/ieee80211_proto.9 b/share/man/man9/ieee80211_ddb.9 similarity index 51% copy from share/man/man9/ieee80211_proto.9 copy to share/man/man9/ieee80211_ddb.9 index f2385719be..3dff41f5d3 100644 --- a/share/man/man9/ieee80211_proto.9 +++ b/share/man/man9/ieee80211_ddb.9 @@ -1,6 +1,5 @@ .\" -.\" Copyright (c) 2004 Bruce M. Simpson -.\" Copyright (c) 2004 Darron Broad +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -24,53 +23,50 @@ .\" 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 diff --git a/share/man/man9/ieee80211_input.9 b/share/man/man9/ieee80211_input.9 index 3b89efc65b..32c16191ed 100644 --- a/share/man/man9/ieee80211_input.9 +++ b/share/man/man9/ieee80211_input.9 @@ -24,92 +24,93 @@ .\" 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 diff --git a/share/man/man9/ieee80211_node.9 b/share/man/man9/ieee80211_node.9 index eb9090eebf..725f8b2eb7 100644 --- a/share/man/man9/ieee80211_node.9 +++ b/share/man/man9/ieee80211_node.9 @@ -24,327 +24,228 @@ .\" 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 diff --git a/share/man/man9/ieee80211_output.9 b/share/man/man9/ieee80211_output.9 index 1feff24d7a..10bc60c244 100644 --- a/share/man/man9/ieee80211_output.9 +++ b/share/man/man9/ieee80211_output.9 @@ -24,172 +24,171 @@ .\" 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 . diff --git a/share/man/man9/ieee80211_proto.9 b/share/man/man9/ieee80211_proto.9 index f2385719be..de219275b9 100644 --- a/share/man/man9/ieee80211_proto.9 +++ b/share/man/man9/ieee80211_proto.9 @@ -1,6 +1,5 @@ .\" -.\" Copyright (c) 2004 Bruce M. Simpson -.\" Copyright (c) 2004 Darron Broad +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -24,53 +23,219 @@ .\" 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 . diff --git a/share/man/man9/ieee80211_radiotap.9 b/share/man/man9/ieee80211_radiotap.9 index 310d95ec06..c0a194c639 100644 --- a/share/man/man9/ieee80211_radiotap.9 +++ b/share/man/man9/ieee80211_radiotap.9 @@ -25,244 +25,280 @@ .\" 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 index 0000000000..a5a5bcd0a0 --- /dev/null +++ b/share/man/man9/ieee80211_regdomain.9 @@ -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 index 0000000000..0141afb0d9 --- /dev/null +++ b/share/man/man9/ieee80211_scan.9 @@ -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 index 0000000000..6d88fbfde9 --- /dev/null +++ b/share/man/man9/ieee80211_vap.9 @@ -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 -- 2.41.0