Provided by: freebsd-manpages_9.2+1-1_all bug

NAME

     IEEE80211 — 802.11 network layer

SYNOPSIS

     #include <net80211/ieee80211_var.h>

     void
     ieee80211_ifattach(struct ieee80211com *ic, const uint8_t macaddr[IEEE80211_ADDR_LEN]);

     void
     ieee80211_ifdetach(struct ieee80211com *ic);

DESCRIPTION

     IEEE 802.11 device drivers are written to use the infrastructure provided by the IEEE80211
     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 IEEE80211 layer for protocol services but
     devices that off-load functionality may bypass the layer to connect directly to the device
     (e.g. the ndis(4) emulation support does this).

     A IEEE80211 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 IEEE80211 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
     IEEE80211 layer with drivers responsible purely for moving data between the host and device.
     Similarly, IEEE80211 handles most ioctl(2) requests without entering the driver; instead
     drivers are notified of state changes that require their involvement.

     The virtual radio interface defined by the IEEE80211 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.

DATA STRUCTURES

     The virtual radio architecture splits state between a single per-device ieee80211com
     structure and one or more 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 ieee80211com structure is allocated by the IEEE80211
     layer as adjunct data to a device's ifnet; it is accessed through the if_l2com structure
     member.  The ieee80211vap structure is allocated by the driver in the “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 IEEE80211 data structures and should
     be exploited to maintain driver-private state together with public IEEE80211 state.

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

     The ieee80211com and 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 IEEE80211 layer and are described below.

DRIVER ATTACH/DETACH

     Drivers attach to the IEEE80211 layer with the ieee80211_ifattach() function.  The driver is
     expected to allocate and setup any device-private data structures before passing control.
     The ieee80211com structure must be pre-initialized with state required to setup the
     IEEE80211 layer:

     ic_ifp       Backpointer to the physical device's ifnet.

     ic_caps      Device/driver capabilities; see below for a complete description.

     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.

     ic_nchan     Number of entries in ic_channels.

     On return from ieee80211_ifattach() the driver is expected to override default callback
     functions in the ieee80211com structure to register it's private routines.  Methods marked
     with a “*” must be provided by the driver.

     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.

     ic_vap_delete*
                  Destroy a vap instance created with ic_vap_create.

     ic_getradiocaps
                  Return the list of calibrated channels for the radio.  The default method
                  returns the current list of channels (space permitting).

     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.

     ic_send_mgmt
                  Send an 802.11 management frame.  The default method fabricates the frame using
                  IEEE80211 state and passes it to the driver through the ic_raw_xmit method.

     ic_raw_xmit  Transmit a raw 802.11 frame.  The default method drops the frame and generates
                  a message on the console.

     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.

     ic_update_mcast
                  Update hardware for a change in the multicast packet filter.  The default
                  method prints a console message.

     ic_update_promisc
                  Update hardware for a change in the promiscuous mode setting.  The default
                  method prints a console message.

     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.

     ic_node_alloc
                  Allocate and initialize a ieee80211_node structure.  This method cannot sleep.
                  The default method allocates zero'd memory using malloc(9).  Drivers should
                  override this method to allocate extended storage for their own needs.  Memory
                  allocated by the driver must be tagged with M_80211_NODE to balance the memory
                  allocation statistics.

     ic_node_free
                  Reclaim storage of a node allocated by ic_node_alloc.  Drivers are expected to
                  interpose their own method to cleanup private state but must call through this
                  method to allow IEEE80211 to reclaim it's private state.

     ic_node_cleanup
                  Cleanup state in a ieee80211_node created by ic_node_alloc.  This operation is
                  distinguished from 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 ic_node_cleanup instead of
                  ic_node_free.

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

     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.

     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
                  ic_node_getsignal.  The default method calculates a filtered average over the
                  last ten samples passed in to ieee80211_input(9) or ieee80211_input_all(9).

     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 ieee80211_input(9) or ieee80211_input_all(9).

     ic_node_getmimoinfo
                  Return MIMO radio state for a station in support of the IEEE80211_IOC_STA_INFO
                  ioctl request.  The default method returns nothing.

     ic_scan_start*
                  Prepare driver/hardware state for scanning.  This callback is done in a
                  sleepable context.

     ic_scan_end*
                  Restore driver/hardware state after scanning completes.  This callback is done
                  in a sleepable context.

     ic_set_channel*
                  Set the current radio channel using ic_curchan.  This callback is done in a
                  sleepable context.

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

     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.

     ic_recv_action
                  Process a received Action frame.  The default method points to
                  ieee80211_recv_action(9) which provides a mechanism for setting up handlers for
                  each Action frame class.

     ic_send_action
                  Transmit an Action frame.  The default method points to
                  ieee80211_send_action(9) which provides a mechanism for setting up handlers for
                  each Action frame class.

     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.

     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.

     ic_addb_response
                  Process a received ADDBA Response Action frame and setup resources as needed
                  for doing transmit A-MPDU.

     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.

     ic_bar_response
                  Process a response to a transmitted BAR control frame.

     ic_ampdu_rx_start
                  Prepare to receive A-MPDU data from the specified station for the TID.

     ic_ampdu_rx_stop
                  Terminate receipt of A-MPDU data from the specified station for the TID.

     Once the IEEE80211 layer is attached to a driver there are two more steps typically done to
     complete the work:

     1.   Setup “radiotap support” for capturing raw 802.11 packets that pass through the device.
          This is done with a call to ieee80211_radiotap_attach(9).

     2.   Do any final device setup like enabling interrupts.

     State is torn down and reclaimed with a call to 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 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
     if_free(9) on the ifnet it allocated for the physical device.

DRIVER CAPABILITIES

     Driver/device capabilities are specified using several sets of flags in the ieee80211com
     structure.  General capabilities are specified by ic_caps.  Hardware cryptographic
     capabilities are specified by ic_cryptocaps.  802.11n capabilities, if any, are specified by
     ic_htcaps.  The IEEE80211 layer propagates a subset of these capabilities to each vap
     through the equivalent fields: iv_caps, iv_cryptocaps, and iv_htcaps.  The following general
     capabilities are defined:

     IEEE80211_C_STA        Device is capable of operating in station (aka Infrastructure) mode.

     IEEE80211_C_8023ENCAP  Device requires 802.3-encapsulated frames be passed for transmit.  By
                            default IEEE80211 will encapsulate all outbound frames as 802.11
                            frames (without a PLCP header).

     IEEE80211_C_FF         Device supports Atheros Fast-Frames.

     IEEE80211_C_TURBOP     Device supports Atheros Dynamic Turbo mode.

     IEEE80211_C_IBSS       Device is capable of operating in adhoc/IBSS mode.

     IEEE80211_C_PMGT       Device supports dynamic power-management (aka power save) in station
                            mode.

     IEEE80211_C_HOSTAP     Device is capable of operating as an Access Point in Infrastructure
                            mode.

     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.

     IEEE80211_C_SWRETRY    Device supports software retry of transmitted frames.

     IEEE80211_C_TXPMGT     Device support dynamic transmit power changes on transmitted frames;
                            also known as Transmit Power Control (TPC).

     IEEE80211_C_SHSLOT     Device supports short slot time operation (for 802.11g).

     IEEE80211_C_SHPREAMBLE
                            Device supports short preamble operation (for 802.11g).

     IEEE80211_C_MONITOR    Device is capable of operating in monitor mode.

     IEEE80211_C_DFS        Device supports radar detection and/or DFS.  DFS protocol support can
                            be handled by IEEE80211 but the device must be capable of detecting
                            radar events.

     IEEE80211_C_MBSS       Device is capable of operating in MeshBSS (MBSS) mode (as defined by
                            802.11s Draft 3.0).

     IEEE80211_C_WPA1       Device supports WPA1 operation.

     IEEE80211_C_WPA2       Device supports WPA2/802.11i operation.

     IEEE80211_C_BURST      Device supports frame bursting.

     IEEE80211_C_WME        Device supports WME/WMM operation (at the moment this is mostly
                            support for sending and receiving QoS frames with EDCF).

     IEEE80211_C_WDS        Device supports transmit/receive of 4-address frames.

     IEEE80211_C_BGSCAN     Device supports background scanning.

     IEEE80211_C_TXFRAG     Device supports transmit of fragmented 802.11 frames.

     IEEE80211_C_TDMA       Device is capable of operating in TDMA mode.

     The follow general crypto capabilities are defined.  In general IEEE80211 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.  IEEE80211 can also handle software Michael calculation
     combined with hardware AES acceleration.

     IEEE80211_CRYPTO_WEP   Device supports hardware WEP cipher.

     IEEE80211_CRYPTO_TKIP  Device supports hardware TKIP cipher.

     IEEE80211_CRYPTO_AES_OCB
                            Device supports hardware AES-OCB cipher.

     IEEE80211_CRYPTO_AES_CCM
                            Device supports hardware AES-CCM cipher.

     IEEE80211_CRYPTO_TKIPMIC
                            Device supports hardware Michael for use with TKIP.

     IEEE80211_CRYPTO_CKIP  Devices supports hardware CKIP cipher.

     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 solely by the IEEE80211 layer.

     IEEE80211_HTCAP_CHWIDTH40
                            Device supports 20/40 channel width operation.

     IEEE80211_HTCAP_SMPS_DYNAMIC
                            Device supports dynamic SM power save operation.

     IEEE80211_HTCAP_SMPS_ENA
                            Device supports static SM power save operation.

     IEEE80211_HTCAP_GREENFIELD
                            Device supports Greenfield preamble.

     IEEE80211_HTCAP_SHORTGI20
                            Device supports Short Guard Interval on 20MHz channels.

     IEEE80211_HTCAP_SHORTGI40
                            Device supports Short Guard Interval on 40MHz channels.

     IEEE80211_HTCAP_TXSTBC
                            Device supports Space Time Block Convolution (STBC) for transmit.

     IEEE80211_HTCAP_RXSTBC_1STREAM
                            Device supports 1 spatial stream for STBC receive.

     IEEE80211_HTCAP_RXSTBC_2STREAM
                            Device supports 1-2 spatial streams for STBC receive.

     IEEE80211_HTCAP_RXSTBC_3STREAM
                            Device supports 1-3 spatial streams for STBC receive.

     IEEE80211_HTCAP_MAXAMSDU_7935
                            Device supports A-MSDU frames up to 7935 octets.

     IEEE80211_HTCAP_MAXAMSDU_3839
                            Device supports A-MSDU frames up to 3839 octets.

     IEEE80211_HTCAP_DSSSCCK40
                            Device supports use of DSSS/CCK on 40MHz channels.

     IEEE80211_HTCAP_PSMP   Device supports PSMP.

     IEEE80211_HTCAP_40INTOLERANT
                            Device is intolerant of 40MHz wide channel use.

     IEEE80211_HTCAP_LSIGTXOPPROT
                            Device supports L-SIG TXOP protection.

     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 transmit of A-MPDU frames.

     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 transmit of A-MSDU frames.

     IEEE80211_HTC_HT       Device supports High Throughput (HT) operation.  This capability must
                            be set to enable 802.11n functionality in IEEE80211.

     IEEE80211_HTC_SMPS     Device supports MIMO Power Save operation.

     IEEE80211_HTC_RIFS     Device supports Reduced Inter Frame Spacing (RIFS).

SEE ALSO

     ioctl(2), ndis(4), 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), malloc(9)