1.\" 2.\" Copyright (c) 2009 Sam Leffler, Errno Consulting 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: head/share/man/man9/ieee80211.9 233648 2012-03-29 05:02:12Z eadler $ 27.\" 28.Dd July 3, 2021 29.Dt IEEE80211 9 30.Os 31.Sh NAME 32.Nm ieee80211 33.Nd 802.11 network layer 34.Sh SYNOPSIS 35.In net/if.h 36.In net/if_media.h 37.In netproto/802_11/ieee80211_var.h 38.Ft void 39.Fn ieee80211_ifattach "struct ieee80211com *ic" 40.Ft void 41.Fn ieee80211_ifdetach "struct ieee80211com *ic" 42.Sh DESCRIPTION 43IEEE 802.11 device drivers are written to use the infrastructure provided 44by the 45.Nm 46software layer. 47This software provides a support framework for drivers that includes 48ifnet cloning, state management, and a user management API by which 49applications interact with 802.11 devices. 50Most drivers depend on the 51.Nm 52layer for protocol services but devices that off-load functionality 53may bypass the layer to connect directly to the device. 54.Pp 55A 56.Nm 57device driver implements a virtual radio API that is exported to 58users through network interfaces (aka vaps) that are cloned from the 59underlying device. 60These interfaces have an operating mode 61(station, adhoc, hostap, wds, monitor, etc.) 62that is fixed for the lifetime of the interface. 63Devices that can support multiple concurrent interfaces allow 64multiple vaps to be cloned. 65This enables construction of interesting applications such as 66an AP vap and one or more WDS vaps 67or multiple AP vaps, each with a different security model. 68The 69.Nm 70layer virtualizes most 802.11 state 71and coordinates vap state changes including scheduling multiple vaps. 72State that is not virtualized includes the current channel and 73WME/WMM parameters. 74Protocol processing is typically handled entirely in the 75.Nm 76layer with drivers responsible purely for moving data between the host 77and device. 78Similarly, 79.Nm 80handles most 81.Xr ioctl 2 82requests without entering the driver; 83instead drivers are notified of state changes that 84require their involvement. 85.Pp 86The virtual radio interface defined by the 87.Nm 88layer means that drivers must be structured to follow specific rules. 89Drivers that support only a single interface at any time must still 90follow these rules. 91.Sh DATA STRUCTURES 92The virtual radio architecture splits state between a single per-device 93.Vt ieee80211com 94structure and one or more 95.Vt ieee80211vap 96structures. 97Drivers are expected to setup various shared state in these structures 98at device attach and during vap creation but otherwise should treat them 99as read-only. 100The 101.Vt ieee80211com 102structure is allocated by the 103.Nm 104layer as adjunct data to a device's 105.Vt ifnet ; 106it is accessed through the 107.Vt if_l2com 108structure member. 109The 110.Vt ieee80211vap 111structure is allocated by the driver in the 112.Dq vap create 113method 114and should be extended with any driver-private state. 115This technique of giving the driver control to allocate data structures 116is used for other 117.Nm 118data structures and should be exploited to maintain driver-private state 119together with public 120.Nm 121state. 122.Pp 123The other main data structures are the station, or node, table 124that tracks peers in the local BSS, and the channel table that defines 125the current set of available radio channels. 126Both tables are bound to the 127.Vt ieee80211com 128structure and shared by all vaps. 129Long-lasting references to a node are counted to guard against 130premature reclamation. 131In particular every packet sent/received holds a node reference 132(either explicitly for transmit or implicitly on receive). 133.Pp 134The 135.Vt ieee80211com 136and 137.Vt ieee80211vap 138structures also hold a collection of method pointers that drivers 139fill-in and/or override to take control of certain operations. 140These methods are the primary way drivers are bound to the 141.Nm 142layer and are described below. 143.Sh DRIVER ATTACH/DETACH 144Drivers attach to the 145.Nm 146layer with the 147.Fn ieee80211_ifattach 148function. 149The driver is expected to allocate and setup any device-private 150data structures before passing control. 151The 152.Vt ieee80211com 153structure must be pre-initialized with state required to setup the 154.Nm 155layer: 156.Bl -tag -width ic_channels 157.It Dv ic_ifp 158Backpointer to the physical device's ifnet. 159.It Dv ic_caps 160Device/driver capabilities; see below for a complete description. 161.It Dv ic_channels 162Table of channels the device is capable of operating on. 163This is initially provided by the driver but may be changed 164through calls that change the regulatory state. 165.It Dv ic_nchan 166Number of entries in 167.Dv ic_channels . 168.El 169.Pp 170On return from 171.Fn ieee80211_ifattach 172the driver is expected to override default callback functions in the 173.Vt ieee80211com 174structure to register its private routines. 175Methods marked with a 176.Dq * 177must be provided by the driver. 178.Bl -tag -width ic_channels 179.It Dv ic_vap_create* 180Create a vap instance of the specified type (operating mode). 181Any fixed BSSID and/or MAC address is provided. 182Drivers that support multi-bssid operation may honor the requested BSSID 183or assign their own. 184.It Dv ic_vap_delete* 185Destroy a vap instance created with 186.Dv ic_vap_create . 187.It Dv ic_getradiocaps 188Return the list of calibrated channels for the radio. 189The default method returns the current list of channels 190(space permitting). 191.It Dv ic_setregdomain 192Process a request to change regulatory state. 193The routine may reject a request or constrain changes (e.g. reduce 194transmit power caps). 195The default method accepts all proposed changes. 196.It Dv ic_send_mgmt 197Send an 802.11 management frame. 198The default method fabricates the frame using 199.Nm 200state and passes it to the driver through the 201.Dv ic_raw_xmit 202method. 203.It Dv ic_raw_xmit 204Transmit a raw 802.11 frame. 205The default method drops the frame and generates a message on the console. 206.It Dv ic_updateslot 207Update hardware state after an 802.11 IFS slot time change. 208There is no default method; the pointer may be NULL in which case 209it will not be used. 210.It Dv ic_update_mcast 211Update hardware for a change in the multicast packet filter. 212The default method prints a console message. 213.It Dv ic_update_promisc 214Update hardware for a change in the promiscuous mode setting. 215The default method prints a console message. 216.It Dv ic_newassoc 217Update driver/device state for association to a new AP (in station mode) 218or when a new station associates (e.g. in AP mode). 219There is no default method; the pointer may be NULL in which case 220it will not be used. 221.It Dv ic_node_alloc 222Allocate and initialize a 223.Vt ieee80211_node 224structure. 225This method cannot sleep. 226The default method allocates zero'd memory using 227.Xr kmalloc 9 . 228Drivers should override this method to allocate extended storage 229for their own needs. 230Memory allocated by the driver must be tagged with 231.Dv M_80211_NODE 232to balance the memory allocation statistics. 233.It Dv ic_node_free 234Reclaim storage of a node allocated by 235.Dv ic_node_alloc . 236Drivers are expected to 237.Em interpose 238their own method to cleanup private state but must call through 239this method to allow 240.Nm 241to reclaim its private state. 242.It Dv ic_node_cleanup 243Cleanup state in a 244.Vt ieee80211_node 245created by 246.Dv ic_node_alloc . 247This operation is distinguished from 248.Dv ic_node_free 249in that it may be called long before the node is actually reclaimed 250to cleanup adjunct state. 251This can happen, for example, when a node must not be reclaimed 252due to references held by packets in the transmit queue. 253Drivers typically interpose 254.Dv ic_node_cleanup 255instead of 256.Dv ic_node_free . 257.It Dv ic_node_age 258Age, and potentially reclaim, resources associated with a node. 259The default method ages frames on the power-save queue (in AP mode) 260and pending frames in the receive reorder queues (for stations using A-MPDU). 261.It Dv ic_node_drain 262Reclaim all optional resources associated with a node. 263This call is used to free up resources when they are in short supply. 264.It Dv ic_node_getrssi 265Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for 266the specified node. 267This interface returns a subset of the information 268returned by 269.Dv ic_node_getsignal . 270The default method calculates a filtered average over the last ten 271samples passed in to 272.Xr ieee80211_input 9 273or 274.Xr ieee80211_input_all 9 . 275.It Dv ic_node_getsignal 276Return the RSSI and noise floor (in .5 dBm units) for a station. 277The default method calculates RSSI as described above; 278the noise floor returned is the last value supplied to 279.Xr ieee80211_input 9 280or 281.Xr ieee80211_input_all 9 . 282.It Dv ic_node_getmimoinfo 283Return MIMO radio state for a station in support of the 284.Dv IEEE80211_IOC_STA_INFO 285ioctl request. 286The default method returns nothing. 287.It Dv ic_scan_start* 288Prepare driver/hardware state for scanning. 289This callback is done in a sleepable context. 290.It Dv ic_scan_end* 291Restore driver/hardware state after scanning completes. 292This callback is done in a sleepable context. 293.It Dv ic_set_channel* 294Set the current radio channel using 295.Vt ic_curchan . 296This callback is done in a sleepable context. 297.It Dv ic_scan_curchan 298Start scanning on a channel. 299This method is called immediately after each channel change 300and must initiate the work to scan a channel and schedule a timer 301to advance to the next channel in the scan list. 302This callback is done in a sleepable context. 303The default method handles active scan work (e.g. sending ProbeRequest 304frames), and schedules a call to 305.Xr ieee80211_scan_next 9 306according to the maximum dwell time for the channel. 307Drivers that off-load scan work to firmware typically use this method 308to trigger per-channel scan activity. 309.It Dv ic_scan_mindwell 310Handle reaching the minimum dwell time on a channel when scanning. 311This event is triggered when one or more stations have been found on 312a channel and the minimum dwell time has been reached. 313This callback is done in a sleepable context. 314The default method signals the scan machinery to advance 315to the next channel as soon as possible. 316Drivers can use this method to preempt further work (e.g. if scanning 317is handled by firmware) or ignore the request to force maximum dwell time 318on a channel. 319.It Dv ic_recv_action 320Process a received Action frame. 321The default method points to 322.Fn ieee80211_recv_action 323which provides a mechanism for setting up handlers for each Action frame class. 324.It Dv ic_send_action 325Transmit an Action frame. 326The default method points to 327.Fn ieee80211_send_action 328which provides a mechanism for setting up handlers for each Action frame class. 329.It Dv ic_ampdu_enable 330Check if transmit A-MPDU should be enabled for the specified station and AC. 331The default method checks a per-AC traffic rate against a per-vap 332threshold to decide if A-MPDU should be enabled. 333This method also rate-limits ADDBA requests so that requests are not 334made too frequently when a receiver has limited resources. 335.It Dv ic_addba_request 336Request A-MPDU transmit aggregation. 337The default method sets up local state and issues an 338ADDBA Request Action frame. 339Drivers may interpose this method if they need to setup private state 340for handling transmit A-MPDU. 341.It Dv ic_addb_response 342Process a received ADDBA Response Action frame and setup resources as 343needed for doing transmit A-MPDU. 344.It Dv ic_addb_stop 345Shutdown an A-MPDU transmit stream for the specified station and AC. 346The default method reclaims local state after sending a DelBA Action frame. 347.It Dv ic_bar_response 348Process a response to a transmitted BAR control frame. 349.It Dv ic_ampdu_rx_start 350Prepare to receive A-MPDU data from the specified station for the TID. 351.It Dv ic_ampdu_rx_stop 352Terminate receipt of A-MPDU data from the specified station for the TID. 353.El 354.Pp 355Once the 356.Nm 357layer is attached to a driver there are two more steps typically done 358to complete the work: 359.Bl -enum 360.It 361Setup 362.Dq radiotap support 363for capturing raw 802.11 packets that pass through the device. 364This is done with a call to 365.Xr ieee80211_radiotap_attach 9 . 366.It 367Do any final device setup like enabling interrupts. 368.El 369.Pp 370State is torn down and reclaimed with a call to 371.Fn ieee80211_ifdetach . 372Note this call may result in multiple callbacks into the driver 373so it should be done before any critical driver state is reclaimed. 374On return from 375.Fn ieee80211_ifdetach 376all associated vaps and ifnet structures are reclaimed or inaccessible 377to user applications so it is safe to teardown driver state without 378worry about being re-entered. 379The driver is responsible for calling 380.Fn if_free 381on the ifnet it allocated for the physical device. 382.Sh DRIVER CAPABILITIES 383Driver/device capabilities are specified using several sets of flags 384in the 385.Vt ieee80211com 386structure. 387General capabilities are specified by 388.Vt ic_caps . 389Hardware cryptographic capabilities are specified by 390.Vt ic_cryptocaps . 391802.11n capabilities, if any, are specified by 392.Vt ic_htcaps . 393The 394.Nm 395layer propagates a subset of these capabilities to each vap through 396the equivalent fields: 397.Vt iv_caps , 398.Vt iv_cryptocaps , 399and 400.Vt iv_htcaps . 401The following general capabilities are defined: 402.Bl -tag -width IEEE80211_C_8023ENCAP 403.It Dv IEEE80211_C_STA 404Device is capable of operating in station (aka Infrastructure) mode. 405.It Dv IEEE80211_C_8023ENCAP 406Device requires 802.3-encapsulated frames be passed for transmit. 407By default 408.Nm 409will encapsulate all outbound frames as 802.11 frames (without a PLCP header). 410.It Dv IEEE80211_C_FF 411Device supports Atheros Fast-Frames. 412.It Dv IEEE80211_C_TURBOP 413Device supports Atheros Dynamic Turbo mode. 414.It Dv IEEE80211_C_IBSS 415Device is capable of operating in adhoc/IBSS mode. 416.It Dv IEEE80211_C_PMGT 417Device supports dynamic power-management (aka power save) in station mode. 418.It Dv IEEE80211_C_HOSTAP 419Device is capable of operating as an Access Point in Infrastructure mode. 420.It Dv IEEE80211_C_AHDEMO 421Device is capable of operating in Adhoc Demo mode. 422In this mode the device is used purely to send/receive raw 802.11 frames. 423.It Dv IEEE80211_C_SWRETRY 424Device supports software retry of transmitted frames. 425.It Dv IEEE80211_C_TXPMGT 426Device support dynamic transmit power changes on transmitted frames; 427also known as Transmit Power Control (TPC). 428.It Dv IEEE80211_C_SHSLOT 429Device supports short slot time operation (for 802.11g). 430.It Dv IEEE80211_C_SHPREAMBLE 431Device supports short preamble operation (for 802.11g). 432.It Dv IEEE80211_C_MONITOR 433Device is capable of operating in monitor mode. 434.It Dv IEEE80211_C_DFS 435Device supports radar detection and/or DFS. 436DFS protocol support can be handled by 437.Nm 438but the device must be capable of detecting radar events. 439.It Dv IEEE80211_C_MBSS 440Device is capable of operating in MeshBSS (MBSS) mode 441(as defined by 802.11s Draft 3.0). 442.It Dv IEEE80211_C_WPA1 443Device supports WPA1 operation. 444.It Dv IEEE80211_C_WPA2 445Device supports WPA2/802.11i operation. 446.It Dv IEEE80211_C_BURST 447Device supports frame bursting. 448.It Dv IEEE80211_C_WME 449Device supports WME/WMM operation 450(at the moment this is mostly support for sending and receiving 451QoS frames with EDCF). 452.It Dv IEEE80211_C_WDS 453Device supports transmit/receive of 4-address frames. 454.It Dv IEEE80211_C_BGSCAN 455Device supports background scanning. 456.It Dv IEEE80211_C_TXFRAG 457Device supports transmit of fragmented 802.11 frames. 458.It Dv IEEE80211_C_TDMA 459Device is capable of operating in TDMA mode. 460.El 461.Pp 462The follow general crypto capabilities are defined. 463In general 464.Nm 465will fall-back to software support when a device is not capable 466of hardware acceleration of a cipher. 467This can be done on a per-key basis. 468.Nm 469can also handle software 470.Dv Michael 471calculation combined with hardware 472.Dv AES 473acceleration. 474.Bl -tag -width IEEE80211_C_8023ENCAP 475.It Dv IEEE80211_CRYPTO_WEP 476Device supports hardware WEP cipher. 477.It Dv IEEE80211_CRYPTO_TKIP 478Device supports hardware TKIP cipher. 479.It Dv IEEE80211_CRYPTO_AES_OCB 480Device supports hardware AES-OCB cipher. 481.It Dv IEEE80211_CRYPTO_AES_CCM 482Device supports hardware AES-CCM cipher. 483.It Dv IEEE80211_CRYPTO_TKIPMIC 484Device supports hardware Michael for use with TKIP. 485.It Dv IEEE80211_CRYPTO_CKIP 486Devices supports hardware CKIP cipher. 487.El 488.Pp 489The follow general 802.11n capabilities are defined. 490The first capabilities are defined exactly as they appear in the 491802.11n specification. 492Capabilities beginning with IEEE80211_HTC_AMPDU are used solely by the 493.Nm 494layer. 495.Bl -tag -width IEEE80211_C_8023ENCAP 496.It Dv IEEE80211_HTCAP_CHWIDTH40 497Device supports 20/40 channel width operation. 498.It Dv IEEE80211_HTCAP_SMPS_DYNAMIC 499Device supports dynamic SM power save operation. 500.It Dv IEEE80211_HTCAP_SMPS_ENA 501Device supports static SM power save operation. 502.It Dv IEEE80211_HTCAP_GREENFIELD 503Device supports Greenfield preamble. 504.It Dv IEEE80211_HTCAP_SHORTGI20 505Device supports Short Guard Interval on 20MHz channels. 506.It Dv IEEE80211_HTCAP_SHORTGI40 507Device supports Short Guard Interval on 40MHz channels. 508.It Dv IEEE80211_HTCAP_TXSTBC 509Device supports Space Time Block Convolution (STBC) for transmit. 510.It Dv IEEE80211_HTCAP_RXSTBC_1STREAM 511Device supports 1 spatial stream for STBC receive. 512.It Dv IEEE80211_HTCAP_RXSTBC_2STREAM 513Device supports 1-2 spatial streams for STBC receive. 514.It Dv IEEE80211_HTCAP_RXSTBC_3STREAM 515Device supports 1-3 spatial streams for STBC receive. 516.It Dv IEEE80211_HTCAP_MAXAMSDU_7935 517Device supports A-MSDU frames up to 7935 octets. 518.It Dv IEEE80211_HTCAP_MAXAMSDU_3839 519Device supports A-MSDU frames up to 3839 octets. 520.It Dv IEEE80211_HTCAP_DSSSCCK40 521Device supports use of DSSS/CCK on 40MHz channels. 522.It Dv IEEE80211_HTCAP_PSMP 523Device supports PSMP. 524.It Dv IEEE80211_HTCAP_40INTOLERANT 525Device is intolerant of 40MHz wide channel use. 526.It Dv IEEE80211_HTCAP_LSIGTXOPPROT 527Device supports L-SIG TXOP protection. 528.It Dv IEEE80211_HTC_AMPDU 529Device supports A-MPDU aggregation. 530Note that any 802.11n compliant device must support A-MPDU receive 531so this implicitly means support for 532.Em transmit 533of A-MPDU frames. 534.It Dv IEEE80211_HTC_AMSDU 535Device supports A-MSDU aggregation. 536Note that any 802.11n compliant device must support A-MSDU receive 537so this implicitly means support for 538.Em transmit 539of A-MSDU frames. 540.It Dv IEEE80211_HTC_HT 541Device supports High Throughput (HT) operation. 542This capability must be set to enable 802.11n functionality 543in 544.Nm . 545.It Dv IEEE80211_HTC_SMPS 546Device supports MIMO Power Save operation. 547.It Dv IEEE80211_HTC_RIFS 548Device supports Reduced Inter Frame Spacing (RIFS). 549.El 550.Sh SEE ALSO 551.Xr ioctl 2 , 552.\".Xr ieee80211_amrr 9 , 553.Xr ieee80211_beacon 9 , 554.Xr ieee80211_bmiss 9 , 555.Xr ieee80211_crypto 9 , 556.Xr ieee80211_ddb 9 , 557.Xr ieee80211_input 9 , 558.Xr ieee80211_node 9 , 559.Xr ieee80211_output 9 , 560.Xr ieee80211_proto 9 , 561.Xr ieee80211_radiotap 9 , 562.Xr ieee80211_regdomain 9 , 563.Xr ieee80211_scan 9 , 564.Xr ieee80211_vap 9 , 565.Xr ifnet 9 , 566.Xr kmalloc 9 567