From owner-svn-src-head@FreeBSD.ORG Wed Aug 12 21:03:21 2009 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 00D9D1065784; Wed, 12 Aug 2009 21:03:17 +0000 (UTC) (envelope-from sam@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id AD5538FC48; Wed, 12 Aug 2009 21:03:17 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id n7CL3HEh076550; Wed, 12 Aug 2009 21:03:17 GMT (envelope-from sam@svn.freebsd.org) Received: (from sam@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id n7CL3Hpw076548; Wed, 12 Aug 2009 21:03:17 GMT (envelope-from sam@svn.freebsd.org) Message-Id: <200908122103.n7CL3Hpw076548@svn.freebsd.org> From: Sam Leffler Date: Wed, 12 Aug 2009 21:03:17 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r196155 - head/share/man/man9 X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Aug 2009 21:03:21 -0000 Author: sam Date: Wed Aug 12 21:03:16 2009 New Revision: 196155 URL: http://svn.freebsd.org/changeset/base/196155 Log: First (early) draft of net80211 documentation. Note this is focused on driver writers (as opposed to folks adding to net80211). Reviewed by: wkoszek Approved by: re (rwatson) Added: head/share/man/man9/ieee80211_amrr.9 (contents, props changed) head/share/man/man9/ieee80211_beacon.9 (contents, props changed) head/share/man/man9/ieee80211_bmiss.9 (contents, props changed) head/share/man/man9/ieee80211_ddb.9 (contents, props changed) head/share/man/man9/ieee80211_regdomain.9 (contents, props changed) head/share/man/man9/ieee80211_scan.9 (contents, props changed) head/share/man/man9/ieee80211_vap.9 (contents, props changed) Deleted: head/share/man/man9/ieee80211_ioctl.9 Modified: head/share/man/man9/Makefile head/share/man/man9/ieee80211.9 head/share/man/man9/ieee80211_crypto.9 head/share/man/man9/ieee80211_input.9 head/share/man/man9/ieee80211_node.9 head/share/man/man9/ieee80211_output.9 head/share/man/man9/ieee80211_proto.9 head/share/man/man9/ieee80211_radiotap.9 Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Wed Aug 12 20:48:50 2009 (r196154) +++ head/share/man/man9/Makefile Wed Aug 12 21:03:16 2009 (r196155) @@ -121,13 +121,19 @@ MAN= accept_filter.9 \ hashinit.9 \ hexdump.9 \ ieee80211.9 \ + ieee80211_amrr.9 \ + ieee80211_beacon.9 \ + ieee80211_bmiss.9 \ ieee80211_crypto.9 \ + ieee80211_ddb.9 \ ieee80211_input.9 \ - ieee80211_ioctl.9 \ ieee80211_node.9 \ ieee80211_output.9 \ ieee80211_proto.9 \ ieee80211_radiotap.9 \ + ieee80211_regdomain.9 \ + ieee80211_scan.9 \ + ieee80211_vap.9 \ ifnet.9 \ inittodr.9 \ insmntque.9 \ @@ -627,52 +633,62 @@ MLINKS+=hash.9 hash32.9 \ MLINKS+=hashinit.9 hashdestroy.9 \ hashinit.9 hashinit_flags.9 \ hashinit.9 phashinit.9 -MLINKS+=ieee80211.9 ieee80211_attach.9 \ - ieee80211.9 ieee80211_chan2ieee.9 \ - ieee80211.9 ieee80211_chan2mode.9 \ - ieee80211.9 ieee80211_ieee2mhz.9 \ - ieee80211.9 ieee80211_ifattach.9 \ - ieee80211.9 ieee80211_ifdetach.9 \ - ieee80211.9 ieee80211_media2rate.9 \ - ieee80211.9 ieee80211_media_change.9 \ - ieee80211.9 ieee80211_media_init.9 \ - ieee80211.9 ieee80211_media_status.9 \ - ieee80211.9 ieee80211_mhz2ieee.9 \ - ieee80211.9 ieee80211_rate2media.9 \ - ieee80211.9 ieee80211_setmode.9 \ - ieee80211.9 ieee80211_watchdog.9 -MLINKS+=ieee80211_crypto.9 ieee80211_crypto_attach.9 \ - ieee80211_crypto.9 ieee80211_crypto_detach.9 \ - ieee80211_crypto.9 ieee80211_wep_crypt.9 -MLINKS+=ieee80211_input.9 ieee80211_decap.9 \ - ieee80211_input.9 ieee80211_recv_mgmt.9 -MLINKS+=ieee80211_ioctl.9 ieee80211_cfgget.9 \ - ieee80211_ioctl.9 ieee80211_cfgset.9 -MLINKS+=ieee80211_node.9 ieee80211_alloc_node.9 \ - ieee80211_node.9 ieee80211_begin_scan.9 \ - ieee80211_node.9 ieee80211_create_ibss.9 \ - ieee80211_node.9 ieee80211_dup_bss.9 \ - ieee80211_node.9 ieee80211_end_scan.9 \ - ieee80211_node.9 ieee80211_find_node.9 \ - ieee80211_node.9 ieee80211_free_allnodes.9 \ +MLINKS+=ieee80211.9 ieee80211_ifattach.9 \ + ieee80211.9 ieee80211_ifdetach.9 +MLINKS+=ieee80211_amrr.9 ieee80211_amrr_init.9 \ + ieee80211_amrr.9 ieee80211_amrr_cleanup.9 \ + ieee80211_amrr.9 ieee80211_amrr_setinterval.9 \ + ieee80211_amrr.9 ieee80211_amrr_node_init.9 \ + ieee80211_amrr.9 ieee80211_amrr_tx_complete.9 \ + ieee80211_amrr.9 ieee80211_amrr_tx_update.9 +MLINKS+=ieee80211_beacon.9 ieee80211_beacon_alloc.9 \ + ieee80211_beacon.9 ieee80211_beacon_update.9 \ + ieee80211_beacon.9 ieee80211_beacon_notify.9 +MLINKS+=ieee80211_bmiss.9 ieee80211_beacon_miss.9 +MLINKS+=ieee80211_crypto.9 ieee80211_key_update_begin.9 \ + ieee80211_crypto.9 ieee80211_key_update_end.9 \ + ieee80211_crypto.9 ieee80211_crypto_newkey.9 \ + ieee80211_crypto.9 ieee80211_crypto_setkey.9 \ + ieee80211_crypto.9 ieee80211_crypto_delglobalkeys.9 \ + ieee80211_crypto.9 ieee80211_crypto_reload_keys.9 \ + ieee80211_crypto.9 ieee80211_crypto_decap.9 \ + ieee80211_crypto.9 ieee80211_crypto_encap.9 \ + ieee80211_crypto.9 ieee80211_crypto_demic.9 \ + ieee80211_crypto.9 ieee80211_crypto_enmic.9 \ + ieee80211_crypto.9 ieee80211_notify_michael_failure.9 \ + ieee80211_crypto.9 ieee80211_notify_replay_failure.9 \ + ieee80211_crypto.9 ieee80211_crypto_register.9 \ + ieee80211_crypto.9 ieee80211_crypto_unregister.9 \ + ieee80211_crypto.9 ieee80211_crypto_available.9 +MLINKS+=ieee80211_input.9 ieee80211_input_all.9 +MLINKS+=ieee80211_node.9 ieee80211_find_rxnode.9 \ + ieee80211_node.9 ieee80211_find_rxnode_withkey.9 \ + ieee80211_node.9 ieee80211_ref_node.9 \ + ieee80211_node.9 ieee80211_unref_node.9 \ ieee80211_node.9 ieee80211_free_node.9 \ ieee80211_node.9 ieee80211_iterate_nodes.9 \ - ieee80211_node.9 ieee80211_lookup_node.9 \ - ieee80211_node.9 ieee80211_next_scan.9 \ - ieee80211_node.9 ieee80211_node_attach.9 \ - ieee80211_node.9 ieee80211_node_detach.9 \ - ieee80211_node.9 ieee80211_node_lateattach.9 \ - ieee80211_node.9 ieee80211_timeout_nodes.9 -MLINKS+=ieee80211_output.9 ieee80211_add_rates.9 \ - ieee80211_output.9 ieee80211_add_xrates.9 \ - ieee80211_output.9 ieee80211_encap.9 \ - ieee80211_output.9 ieee80211_send_mgmt.9 -MLINKS+=ieee80211_proto.9 ieee80211_dump_pkt.9 \ - ieee80211_proto.9 ieee80211_fix_rate.9 \ - ieee80211_proto.9 ieee80211_print_essid.9 \ - ieee80211_proto.9 ieee80211_proto_attach.9 \ - ieee80211_proto.9 ieee80211_proto_detach.9 -MLINKS+=ieee80211_radiotap.9 radiotap.9 + ieee80211_node.9 ieee80211_dump_node.9 \ + ieee80211_node.9 ieee80211_dump_nodes.9 +MLINKS+=ieee80211_output.9 M_WME_GETAC.9 \ + ieee80211_output.9 M_SEQNO_GET.9 \ + ieee80211_output.9 ieee80211_process_callback.9 +MLINKS+=ieee80211_proto.9 ieee80211_new_state.9 \ + ieee80211_proto.9 ieee80211_start_all.9 \ + ieee80211_proto.9 ieee80211_stop_all.9 \ + ieee80211_proto.9 ieee80211_suspend_all.9 \ + ieee80211_proto.9 ieee80211_resume_all.9 \ + ieee80211_proto.9 ieee80211_waitfor_parent.9 +MLINKS+=ieee80211_radiotap.9 radiotap.9 \ + ieee80211_radiotap.9 ieee80211_radiotap_attach.9 \ + ieee80211_radiotap.9 ieee80211_radiotap_active_vap.9 \ + ieee80211_radiotap.9 ieee80211_radiotap_active.9 \ + ieee80211_radiotap.9 ieee80211_radiotap_tx.9 +MLINKS+=ieee80211_regdomain.9 ieee80211_init_channels.9 \ + ieee80211_regdomain.9 ieee80211_sort_channels.9 \ + ieee80211_regdomain.9 ieee80211_alloc_countryie.9 +MLINKS+=ieee80211_vap.9 ieee80211_vap_setup.9 \ + ieee80211_vap.9 ieee80211_vap_attach.9 \ + ieee80211_vap.9 ieee80211_vap_detach.9 MLINKS+=ifnet.9 ifaddr.9 \ ifnet.9 if_data.9 \ ifnet.9 ifqueue.9 Modified: head/share/man/man9/ieee80211.9 ============================================================================== --- head/share/man/man9/ieee80211.9 Wed Aug 12 20:48:50 2009 (r196154) +++ head/share/man/man9/ieee80211.9 Wed Aug 12 21:03:16 2009 (r196155) @@ -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 @@ -25,236 +24,538 @@ .\" SUCH DAMAGE. .\" .\" $FreeBSD$ -.\" $Id: ieee80211.9,v 1.5 2004/03/04 12:33:27 bruce Exp $ .\" -.Dd March 2, 2004 -.Dt IEEE80211 9 +.Dd August 4, 2009 +.Dt NET80211 9 .Os .Sh NAME -.Nm ieee80211_ifattach , ieee80211_ifdetach , -.Nm ieee80211_mhz2ieee , ieee80211_chan2ieee , ieee80211_ieee2mhz , -.Nm ieee80211_media_init , ieee80211_media_change , ieee80211_media_status , -.Nm ieee80211_watchdog , -.Nm ieee80211_setmode , ieee80211_chan2mode , -.Nm ieee80211_rate2media , ieee80211_media2rate -.Nd core 802.11 network stack functions +.Nm net80211 +.Nd 802.11 network layer .Sh SYNOPSIS .In net80211/ieee80211_var.h -.In net80211/ieee80211_proto.h .Ft void -.Fn ieee80211_ifattach "struct ifnet *ifp" +.Fn ieee80211_ifattach "struct ieee80211com *ic" "const uint8_t macaddr[IEEE80211_ADDR_LEN]" .Ft void -.Fn ieee80211_ifdetach "struct ifnet *ifp" -.Ft u_int -.Fn ieee80211_mhz2ieee "u_int freq" "u_int flags" -.Ft u_int -.Fn ieee80211_chan2ieee "struct ieee80211com *ic" "struct ieee80211_channel *c" -.Ft u_int -.Fn ieee80211_ieee2mhz "u_int chan" "u_int flags" -.Ft void -.Fo ieee80211_media_init -.Fa "struct ifnet *ifp" "ifm_change_cb_t media_change" -.Fa "ifm_stat_cb_t media_stat" -.Fc -.Fa int -.Fn ieee80211_media_change "struct ifnet *ifp" -.Fa void -.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr" -.Ft void -.Fn ieee80211_watchdog "struct ifnet *ifp" -.Ft int -.Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode" -.Ft enum ieee80211_phymode -.Fo ieee80211_chan2mode -.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" -.Fc -.Ft int -.Fo ieee80211_rate2media -.Fa "struct ieee80211com *ic" "int rate" "enum ieee80211_phymode mode" -.Fc -.Ft int -.Fn ieee80211_media2rate "int mword" +.Fn ieee80211_ifdetach "struct ieee80211com *ic" .Sh DESCRIPTION -The -.Nm ieee80211 -collection of functions are used to manage wireless network interfaces in the -system which use the system's software 802.11 network stack. -Most of these functions require that attachment to the stack is performed -before calling. -Several utility functions are also provided; these are safe to call from -any driver without prior initialization. +IEEE 802.11 device drivers are written to use the infrastructure provided +by the +.Nm +software layer. +This software provides a support framework for drivers that includes +ifnet cloning, state management, and a user management API by which +applications interact with 802.11 devices. +Most drivers depend on the +.Nm +layer for protocol services but devices that off-load functionality +may bypass the layer to connect directly to the device +(e.g. the +.Xr ndis 4 +emulation support does this). +.Pp +A +.Nm +device driver implements a virtual radio API that is exported to +users through network interfaces (aka vaps) that are cloned from the +underlying device. +These interfaces have an operating mode +(station, adhoc, hostap, wds, monitor, etc.) +that is fixed for the lifetime of the interface. +Devices that can support multiple concurrent interfaces allow +multiple vaps to be cloned. +This enables construction of interesting applications such as +an AP vap and one or more WDS vaps +or multiple AP vaps, each with a different security model. +The +.Nm +layer virtualizes most 802.11 state +and coordinates vap state changes including scheduling multiple vaps. +State that is not virtualized includes the current channel and +WME/WMM parameters. +Protocol processing is typically handled entirely in the +.Nm +layer with drivers responsible purely for moving data between the host +and device. +Similarly, +.Nm +handles most +.Xr ioctl 2 +requests without entering the driver; +instead drivers are notified of state changes that +require their involvement. +.Pp +The virtual radio interface defined by the +.Nm +layer means that drivers must be structured to follow specific rules. +Drivers that support only a single interface at any time must still +follow these rules. +.Sh DATA STRUCTURES +The virtual radio architecture splits state between a single per-device +.Vt ieee80211com +structure and one or more +.Vt ieee80211vap +structures. +Drivers are expected to setup various shared state in these structures +at device attach and during vap creation but otherwise should treat them +as read-only. +The +.Vt ieee80211com +structure is allocated by the +.Nm +layer as adjunct data to a device's +.Vt ifnet ; +it is accessed through the +.Vt if_l2com +structure member. +The +.Vt ieee80211vap +structure is allocated by the driver in the +.Dq vap create +method +and should be extended with any driver-private state. +This technique of giving the driver control to allocate data structures +is used for other +.Nm +data structures and should be exploited to maintain driver-private state +together with public +.Nm +state. +.Pp +The other main data structures are the station, or node, table +that tracks peers in the local BSS, and the channel table that defines +the current set of available radio channels. +Both tables are bound to the +.Vt ieee80211com +structure and shared by all vaps. +Long-lasting references to a node are counted to guard against +premature reclamation. +In particular every packet sent/received holds a node reference +(either explicitly for transmit or implicitly on receive). .Pp -.\" -The -.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; The -.Vt struct ifnet -instance pointed to by -.Fa ifp -MUST be an instance of -.Vt struct ieee80211com , -with various fields initialized to tell -.Nm ieee80211 -about its capabilities. -This function performs Ethernet and BPF attachment (by calling -.Fn ether_ifattach +.Vt ieee80211com and -.Fn bpfattach2 ) -on behalf of the caller. -It also implements the -.Vt ifmedia -interface. +.Vt ieee80211vap +structures also hold a collection of method pointers that drivers +fill-in and/or override to take control of certain operations. +These methods are the primary way drivers are bound to the +.Nm +layer and are described below. +.Sh DRIVER ATTACH/DETACH +Drivers attach to the +.Nm +layer with the +.Fn ieee80211_ifattach +function. +The driver is expected to allocate and setup any device-private +data structures before passing control. +The +.Vt ieee80211com +structure must be pre-initialized with state required to setup the +.Nm +layer: +.Bl -tag -width ic_channels +.It Dv ic_ifp +Backpointer to the physical device's ifnet. +.It Dv ic_caps +Device/driver capabilities; see below for a complete description. +.It Dv ic_channels +Table of channels the device is capable of operating on. +This is initially provided by the driver but may be changed +through calls that change the regulatory state. +.It Dv ic_nchan +Number of entries in +.Dv ic_channels . +.El .Pp -.\" -The +On return from +.Fn ieee80211_ifattach +the driver is expected to override default callback functions in the +.Vt ieee80211com +structure to register it's private routines. +Methods marked with a +.Dq * +must be provided by the driver. +.Bl -tag -width ic_channels +.It Dv ic_vap_create* +Create a vap instance of the specified type (operating mode). +Any fixed BSSID and/or MAC address is provided. +Drivers that support multi-bssid operation may honor the requested BSSID +or assign their own. +.It Dv ic_vap_delete* +Destroy a vap instance created with +.Dv ic_vap_create . +.It Dv ic_getradiocaps +Return the list of calibrated channels for the radio. +The default method returns the current list of channels +(space permitting). +.It Dv ic_setregdomain +Process a request to change regulatory state. +The routine may reject a request or constrain changes (e.g. reduce +transmit power caps). +The default method accepts all proposed changes. +.It Dv ic_send_mgmt +Send an 802.11 management frame. +The default method fabricates the frame using +.Nm +state and passes it to the driver through the +.Dv ic_raw_xmit +method. +.It Dv ic_raw_xmit +Transmit a raw 802.11 frame. +The default method drops the frame and generates a message on the console. +.It Dv ic_updateslot +Update hardware state after an 802.11 IFS slot time change, +There is no default method; the pointer may be NULL in which case +it will not be used. +.It Dv ic_update_mcast +Update hardware for a change in the multicast packet filter, +The default method prints a console message. +.It Dv ic_update_promisc +Update hardware for a change in the promiscuous mode setting. +The default method prints a console message. +.It Dv ic_newassoc +Update driver/device state for association to a new AP (in station mode) +or when a new station associates (e.g. in AP mode). +There is no default method; the pointer may be NULL in which case +it will not be used. +.It Dv ic_node_alloc +Allocate and initialize a +.Vt ieee80211_node +structure. +This method cannot sleep. +The default method allocates zero'd memory using +.Xr malloc 9. +Drivers should override this method to allocate extended storage +for their own needs. +Memory allocated by the driver must be tagged with +.Dv M_80211_NODE +to balance the memory allocation statistics. +.It Dv ic_node_free +Reclaim storage of a node allocated by +.Dv ic_node_alloc . +Drivers are expected to +.Em interpose +their own method to cleanup private state but must call through +this method to allow +.Nm +to reclaim it's private state. +.It Dv ic_node_cleanup +Cleanup state in a +.Vt ieee80211_node +created by +.Dv ic_node_alloc . +This operation is distinguished from +.Dv ic_node_free +in that it may be called long before the node is actually reclaimed +to cleanup adjunct state. +This can happen, for example, when a node must not be reclaimed +due to references held by packets in the transmit queue. +Drivers typically interpose +.Dv ic_node_cleanup +instead of +.Dv ic_node_free . +.It Dv ic_node_age +Age, and potentially reclaim, resources associated with a node. +The default method ages frames on the power-save queue (in AP mode) +and pending frames in the receive reorder queues (for stations using A-MPDU). +.It Dv ic_node_drain +Reclaim all optional resources associated with a node. +This call is used to free up resources when they are in short supply, +.It Dv ic_node_getrssi +Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for +the specified node. +This interface returns a subset of the information +returned by +.Dv ic_node_getsignal , +The default method calculates a filtered average over the last ten +samples passed in to +.Xr ieee80211_input 9 +or +.Xr ieee80211_input_all 9 . +.It Dv ic_node_getsignal +Return the RSSI and noise floor (in .5 dBm units) for a station. +The default method calculates RSSI as described above; +the noise floor returned is the last value supplied to +.Xr ieee80211_input 9 +or +.Xr ieee80211_input_all 9 . +.It Dv ic_node_getmimoinfo +Return MIMO radio state for a station in support of the +.Dv IEEE80211_IOC_STA_INFO +ioctl request. +The default method returns nothing. +.It Dv ic_scan_start* +Prepare driver/hardware state for scanning. +This callback is done in a sleepable context. +.It Dv ic_scan_end* +Restore driver/hardware state after scanning completes. +This callback is done in a sleepable context. +.It Dv ic_set_channel* +Set the current radio channel using +.Vt ic_curchan . +This callback is done in a sleepable context. +.It Dv ic_scan_curchan +Start scanning on a channel. +This method is called immediately after each channel change +and must initiate the work to scan a channel and schedule a timer +to advance to the next channel in the scan list. +This callback is done in a sleepable context. +The default method handles active scan work (e.g. sending ProbRequest +frames), and schedules a call to +.Xr ieee80211_scan_next 9 +according to the maximum dwell time for the channel. +Drivers that off-load scan work to firmware typically use this method +to trigger per-channel scan activity. +.It Dv ic_scan_mindwell +Handle reaching the minimum dwell time on a channel when scanning. +This event is triggered when one or more stations have been found on +a channel and the minimum dwell time has been reached. +This callback is done in a sleepable context. +The default method signals the scan machinery to advance +to the next channel as soon as possible. +Drivers can use this method to preempt further work (e.g. if scanning +is handled by firmware) or ignore the request to force maximum dwell time +on a channel. +.It Dv ic_recv_action +Process a received Action frame. +The default method points to +.Xr ieee80211_recv_action 9 +which provides a mechanism for setting up handlers for each Action frame class. +.It Dv ic_send_action +Transmit an Action frame. +The default method points to +.Xr ieee80211_send_action 9 +which provides a mechanism for setting up handlers for each Action frame class. +.It Dv ic_ampdu_enable +Check if transmit A-MPDU should be enabled for the specified station and AC. +The default method checks a per-AC traffic rate against a per-vap +threshold to decide if A-MPDU should be enabled. +This method also rate-limits ADDBA requests so that requests are not +made too frequently when a receiver has limited resources. +.It Dv ic_addba_request +Request A-MPDU transmit aggregation. +The default method sets up local state and issues an +ADDBA Request Action frame. +Drivers may interpose this method if they need to setup private state +for handling transmit A-MPDU. +.It Dv ic_addb_response +Process a received ADDBA Response Action frame and setup resources as +needed for doing transmit A-MPDU, +.It Dv ic_addb_stop +Shutdown an A-MPDU transmit stream for the specified station and AC. +The default method reclaims local state after sending a DelBA Action frame. +.It Dv ic_bar_response +Process a response to a transmitted BAR control frame. +.It Dv ic_ampdu_rx_start +Prepare to receive A-MPDU data from the specified station for the TID. +.It Dv ic_ampdu_rx_stop +Terminate receipt of A-MPDU data from the specified station for the TID. +.El +.Pp +Once the +.Nm +layer is attached to a driver there are two more steps typically done +to complete the work: +.Bl -enum +.It +Setup +.Dq radiotap support +for capturing raw 802.11 packets that pass through the device. +This is done with a call to +.Xr ieee80211_radiotap_attach 9 . +.It +Do any final device setup like enabling interrupts. +.El +.Pp +State is torn down and reclaimed with a call to +.Fn ieee80211_ifdetach . +Note this call may result in multiple callbacks into the driver +so it should be done before any critical driver state is reclaimed. +On return from .Fn ieee80211_ifdetach -function frees any -.Nm ieee80211 -structures associated with the driver, and performs Ethernet and BPF -detachment on behalf of the caller. -.Pp -.\" -The -.Fn ieee80211_mhz2ieee -utility function converts the frequency -.Fa freq -(specified in MHz) to an IEEE 802.11 channel number. -The -.Fa flags -argument is a hint which specifies whether the frequency is in -the 2GHz ISM band -.Pq Vt IEEE80211_CHAN_2GHZ -or the 5GHz band -.Pq Vt IEEE80211_CHAN_5GHZ ; -appropriate clipping of the result is then performed. -.Pp -.\" -The -.Fn ieee80211_chan2ieee -function converts the channel specified in -.Fa *c -to an IEEE channel number for the driver -.Fa ic . -If the conversion would be invalid, an error message is printed to the -system console. -This function REQUIRES that the driver is hooked up to the -.Nm ieee80211 -subsystem. -.Pp -.\" -The -.Fn ieee80211_ieee2mhz -utility function converts the IEEE channel number -.Ft chan -to a frequency (in MHz). -The -.Fa flags -argument is a hint which specifies whether the frequency is in -the 2GHz ISM band -.Pq Vt IEEE80211_CHAN_2GHZ -or the 5GHz band -.Pq Vt IEEE80211_CHAN_5GHZ ; -appropriate clipping of the result is then performed. -.Pp -.\" -The -.Fn ieee80211_media_init -function initializes media data structures used by the -.Vt ifmedia -interface, for the driver -.Fa ifp . -It must be called by the driver after calling -.Fn ieee80211_attach -and before calling most -.Nm ieee80211 -functions. -The -.Fa media_change -and -.Fa media_stat -arguments specify helper functions which will be invoked by the -.Vt ifmedia -framework when the user changes or queries media options, -using a command such as -.Xr ifconfig 8 . -.Pp -.\" -The -.Fn ieee80211_media_status +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 +.Nm +layer propagates a subset of these capabilities to each vap through +the equivalent fields: +.Vt iv_caps , +.Vt iv_cryptocaps , and -.Fn ieee80211_media_change -functions are device-independent handlers for -.Vt ifmedia -commands and are not intended to be called directly. -.Pp -.\" -The -.Fn ieee80211_watchdog -function is intended to be called from a driver's -.Va if_watchdog -routine. -It is used to perform periodic cleanup of state within the software 802.11 -stack, as well as timing out scans. -.Pp -.\" -The -.Fn ieee80211_setmode -function is called from within the 802.11 stack to change the mode -of the driver's PHY; it is not intended to be called directly. -.Pp -.\" -The -.Fn ieee80211_chan2mode -function returns the PHY mode required for use with the channel -.Fa chan -on the device -.Fa ic . -This is typically used when selecting a rate set, to be advertised in -beacons, for example. -.Pp -.\" -The -.Fn ieee80211_rate2media -function converts the bit rate -.Fa rate -(measured in units of 0.5Mbps) to an -.Vt ifmedia -sub-type, for the device -.Fa ic -running in PHY mode -.Fa mode . -The -.Fn ieee80211_media2rate -performs the reverse of this conversion, returning the bit rate (in 0.5Mbps -units) corresponding to an -.Vt ifmedia -sub-type. -.\" +.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 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 follow general 802.11n capabilities are defined. +The first capabilities are defined exactly as they appear in the +802.11n specification. +Capabilities beginning with IEEE80211_HTC_AMPDU are used soley by the +.Nm +layer. +.Bl -tag -width IEEE80211_C_8023ENCAP +.It Dv IEEE80211_HTCAP_CHWIDTH40 +Device supports 20/40 channel width operation. +.It Dv IEEE80211_HTCAP_SMPS_DYNAMIC +Device supports dynamic SM power save operation. +.It Dv IEEE80211_HTCAP_SMPS_ENA +Device supports static SM power save operation. +.It Dv IEEE80211_HTCAP_GREENFIELD +Device supports Greenfield preamble. +.It Dv IEEE80211_HTCAP_SHORTGI20 +Device supports Short Guard Interval on 20MHz channels. +.It Dv IEEE80211_HTCAP_SHORTGI40 +Device supports Short Guard Interval on 40MHz channels. +.It Dv IEEE80211_HTCAP_TXSTBC +Device supports Space Time Block Convolution (STBC) for transmit. +.It Dv IEEE80211_HTCAP_RXSTBC_1STREAM +Device supports 1 spatial stream for STBC receive. +.It Dv IEEE80211_HTCAP_RXSTBC_2STREAM +Device supports 1-2 spatial streams for STBC receive. +.It Dv IEEE80211_HTCAP_RXSTBC_3STREAM +Device supports 1-3 spatial streams for STBC receive. +.It Dv IEEE80211_HTCAP_MAXAMSDU_7935 +Device supports A-MSDU frames up to 7935 octets. +.It Dv IEEE80211_HTCAP_MAXAMSDU_3839 +Device supports A-MSDU frames up to 3839 octets. +.It Dv IEEE80211_HTCAP_DSSSCCK40 +Device supports use of DSSS/CCK on 40MHz channels. +.It Dv IEEE80211_HTCAP_PSMP +Device supports PSMP. +.It Dv IEEE80211_HTCAP_40INTOLERANT +Device is intolerant of 40MHz wide channel use. +.It Dv IEEE80211_HTCAP_LSIGTXOPPROT +Device supports L-SIG TXOP protection. +.It Dv IEEE80211_HTC_AMPDU +Device supports A-MPDU aggregation. +Note that any 802.11n compliant device must support A-MPDU receive +so this implicitly means support for +.Em transmit +of A-MPDU frames. +.It Dv IEEE80211_HTC_AMSDU +Device supports A-MSDU aggregation. +Note that any 802.11n compliant device must support A-MSDU receive +so this implicitly means support for +.Em transmit +of A-MSDU frames. +.It Dv IEEE80211_HTC_HT +Device supports High Throughput (HT) operation. +This capability must be set to enable 802.11n functionality +in +.Nm . +.It Dv IEEE80211_HTC_SMPS +Device supports MIMO Power Save operation. +.It Dv IEEE80211_HTC_RIFS +Device supports Reduced Inter Frame Spacing (RIFS). +.El .Sh SEE ALSO -.Xr ieee80211_crypto 9 , +.Xr ioctl 2 , +.Xr ndis 4 , .Xr ieee80211_input 9 , -.Xr ieee80211_ioctl 9 , -.Xr ieee80211_node 9 , -.Xr ieee80211_output 9 , -.Xr ieee80211_proto 9 , -.Xr ieee80211_radiotap 9 , -.Xr ifnet 9 -.Sh HISTORY -The -.Nm ieee80211 -series of functions first appeared in -.Nx 1.5 , -and were later ported to -.Fx 4.6 . -.Sh AUTHORS -.An -nosplit -This manual page was written by -.An Bruce M. Simpson Aq bms@FreeBSD.org -and -.An Darron Broad Aq darron@kewl.org . +.Xr ieee80211_input_all 9 , +.Xr ieee80211_scan_next 9 , +.Xr ieee80211_recv_action 9 , +.Xr ieee80211_send_action 9 , +.Xr ieee80211_radiotap_attach 9 , +.Xr ifnet 9 , +.Xr malloc 9 . Added: head/share/man/man9/ieee80211_amrr.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/ieee80211_amrr.9 Wed Aug 12 21:03:16 2009 (r196155) @@ -0,0 +1,194 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 4, 2009 +.Dt IEEE8021_AMRR 9 +.Os +.Sh NAME +.Nm ieee80211_amrr +.Nd 802.11 network driver transmit rate control support +.Sh SYNOPSIS +.In net80211/ieee80211_amrr.h +.Ft void +.Fo ieee80211_amrr_init +.Fa "struct ieee80211_amrr *" +.Fa "struct ieee80211vap *" +.Fa "int amin" +.Fa "int amax" +.Fa "int interval" +.Fc +.\" +.Ft void +.Fn ieee80211_amrr_cleanup "struct ieee80211_amrr *" +.\" +.Ft void +.Fn ieee80211_amrr_setinterval "struct ieee80211_amrr *" "int interval" +.\" +.Ft void +.Fo ieee80211_amrr_node_init +.Fa "struct ieee80211_amrr *" +.Fa "struct ieee80211_amrr_node *" +.Fa "struct ieee80211_node *" +.Fc +.\" +.Ft int +.Fo ieee80211_amrr_choose +.Fa "struct ieee80211_node *" +.Fa "struct ieee80211_amrr_node *" +.Fc +.\" +.Ft void +.Fo ieee80211_amrr_tx_complete +.Fa "struct ieee80211_amrr_node *" +.Fa "int ok" +.Fa "int retries" +.Fc +.\" +.Ft void +.Fo ieee80211_amrr_tx_update +.Fa "struct ieee80211_amrr_node *" +.Fa "int txnct" +.Fa "int success" +.Fa "int retrycnt" +.Fc +.Sh DESCRIPTION +.Nm +is an implementation of the AMRR transmit rate control algorithm +for drivers that use the +.Nm net80211 +software layer. +A rate control algorithm is responsible for choosing the transmit +rate for each frame. +To maximize throughput algorithms try to use the highest rate that +is appropriate for the operating conditions. +The rate will vary as conditions change; the distance between two stations +may change, transient noise may be present that affects signal quality, +etc. +.Nm +uses very simple information from a driver to do it's job: +whether a frame was successfully delivered and how many transmit +attempts were made. +While this enables its use with virtually any wireless device it +limits it's effectiveness--do not expect it to function well in +difficult environments and/or respond quickly to changing conditions. +.Pp +.Nm +requires per-vap state and per-node state for each station it is to +select rates for. *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***