IEEE80211(9)

💖 IEEE80211 — the 802.11 network layer 💖

okay bestie, welcome to IEEE80211(9) from the Kernel Developer's Manual, aka the group chat where all your wireless drivers come to hang out. this is part one, we're just getting started, no sign-off, we have so much to cover 🦋

---

✨ NAME ✨

IEEE80211 — the 802.11 network layer. yes that's the whole thing, it's giving humble but it runs your wifi 💅

---

🌸 SYNOPSIS 🌸

#include <net80211/ieee80211_var.h>

void
ieee80211_ifattach(struct ieee80211com *ic);

void
ieee80211_ifdetach(struct ieee80211com *ic);

int
ieee80211_mhz2ieee(u_int freq, u_int flags);

int
ieee80211_chan2ieee(struct ieee80211com *ic,
    const struct ieee80211_channel *c);

u_int
ieee80211_ieee2mhz(u_int chan, u_int flags);

int
ieee80211_media_change(struct ifnet *ifp);

void
ieee80211_media_status(struct ifnet *ifp, struct ifmediareq *imr);

int
ieee80211_setmode(struct ieee80211com *ic, enum ieee80211_phymode mode);

enum ieee80211_phymode
ieee80211_chan2mode(const struct ieee80211_channel *chan);

int
ieee80211_rate2media(struct ieee80211com *ic, int rate,
    enum ieee80211_phymode mode);

int
ieee80211_media2rate(int mword);

---

👑 DESCRIPTION 👑

so here's the tea 🍓: 802.11 device drivers are written to use the infrastructure that the IEEE80211 software layer provides. this software is basically the support framework for drivers — it handles ifnet cloning, state management, and a user management API so that applications can talk to 802.11 devices. most drivers lean on the IEEE80211 layer for protocol services, but devices that off-load functionality may bypass the layer and connect directly to the device instead (like, for example, the ndis(4) emulation support does exactly that 🙈).

an IEEE80211 device driver implements a virtual radio API that gets 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.) and that mode is fixed for the lifetime of the interface — no take-backs, it is what it is 💀. devices that can support multiple concurrent interfaces let you clone multiple vaps, which unlocks some genuinely iconic applications like an AP vap plus one or more WDS vaps, or multiple AP vaps each with a different security model. main character energy fr fr.

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 ever entering the driver; instead, drivers get notified of state changes that actually require their involvement.

because the virtual radio interface is defined by the IEEE80211 layer, drivers must be structured to follow specific rules. and yes, even drivers that support only a single interface at any time still have to follow these rules — no exceptions, bestie 🫶.

most of these functions require that attachment to the stack is performed before calling. do that first or things get weird.

okay now let's go function by function, stay with me:

• the ieee80211_ifattach() function attaches the wireless network interface ic to the 802.11 network stack layer. this one must be called before using any of the IEEE80211 functions that need to store driver state across invocations. it's the "hi nice to meet you" of the whole relationship ✨
• the ieee80211_ifdetach() function frees any IEEE80211 structures associated with the driver, and it performs Ethernet and BPF detachment on behalf of the caller. it's the "ok bye" 💜
• the ieee80211_mhz2ieee() utility function converts the frequency freq (specified in MHz) to an IEEE 802.11 channel number. the flags argument is a hint that says whether the frequency is in the 2GHz ISM band (IEEE80211_CHAN_2GHZ) or the 5GHz band (IEEE80211_CHAN_5GHZ); appropriate clipping of the result is then performed.
• the ieee80211_chan2ieee() function converts the channel specified in *c to an IEEE channel number for the driver ic. if the conversion would be invalid, an error message gets printed to the system console. this function REQUIRES that the driver is hooked up to the IEEE80211 subsystem — no hookup, no vibes 😭
• the ieee80211_ieee2mhz() utility function converts the IEEE channel number chan to a frequency (in MHz). the flags argument is a hint that says whether the frequency is in the 2GHz ISM band (IEEE80211_CHAN_2GHZ) or the 5GHz band (IEEE80211_CHAN_5GHZ); appropriate clipping of the result is then performed. it's the reverse glow-up of ieee80211_mhz2ieee() 🦋
• the ieee80211_media_status() and ieee80211_media_change() functions are device-independent handlers for ifmedia commands, and they are not intended to be called directly. hands off, they're doing their own thing 🙅
• the 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 either. internal business only 💅
• the ieee80211_chan2mode() function returns the PHY mode required for use with the channel chan. this is typically used when selecting a rate set — to be advertised in beacons, for example.
• the ieee80211_rate2media() function converts the bit rate rate (measured in units of 0.5Mbps) to an ifmedia sub-type, for the device ic running in PHY mode mode. and the ieee80211_media2rate() function performs the reverse of this conversion, returning the bit rate (in 0.5Mbps units) corresponding to an ifmedia sub-type. they're a matched set, a duo, iconic ⭐

---

🎀 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 set up various shared state in these structures at device attach and during vap creation, but otherwise they should treat them as read-only — look, don't touch, bestie 🙈

• the ieee80211com structure is allocated by the IEEE80211 layer as adjunct data to a device's ifnet; you access it through the if_l2com structure member.
• the ieee80211vap structure is allocated by the driver in the “vap create” method, and it 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 too, and you should absolutely exploit it to keep driver-private state together with public IEEE80211 state. it's a whole system, it's cute 🌈

the other main data structures are:

• the station, or node, table, which tracks peers in the local BSS
• the channel table, which 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 — specifically, every packet sent/received holds a node reference (either explicitly for transmit or implicitly on receive). protect the node, protect the vibe 🔥

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 they're described below. lowkey the most important part, stay tuned ✨

---

okay that's part one, we are NOT done, more is coming, don't go anywhere 💖

💖 DRIVER ATTACH/DETACH 💖

okay so bestie, this is where your driver and the IEEE80211 layer become official 💍. Drivers attach with the ieee80211_ifattach() function, and here's the tea: your driver is expected to allocate and set up all its device-private data structures before handing over control. No pressure, just do it first.

The ieee80211com structure has to be pre-initialized with the state needed to set up the IEEE80211 layer, and that means these four things:

• ic_ifp — a backpointer to the physical device's ifnet. it's giving "who's your parent" energy.
• ic_caps — the device/driver capabilities. full description below, don't skip it ✨
• ic_channels — the table of channels your device can operate on. the driver provides this at first, but it can change later through calls that change the regulatory state. so it's not forever-locked, bestie.
• ic_nchan — the number of entries in ic_channels. count them, queen 👑

On the way back from ieee80211_ifattach(), the driver is expected to override the default callback functions in the ieee80211com structure to register its private routines. And heads up: methods marked with a * must be provided by the driver. mandatory. no skips. 🚨

• ic_vap_create* — create a vap instance of the specified type (aka the operating mode). any fixed BSSID and/or MAC address gets provided. drivers that support multi-bssid operation may honor the requested BSSID or assign their own — their choice, their vibes.
• ic_vap_delete* — destroy a vap instance that was created with ic_vap_create. bye bestie 👋
• 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. this routine may reject a request or constrain changes (like reducing transmit power caps). the default method accepts all proposed changes — yes, all of them, no questions.
• 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 just drops the frame and generates a message on the console 💀 (rip frame).
• 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 just won't 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 (like in AP mode). there is no default method; the pointer may be NULL, in which case it won't be used.
• ic_node_alloc — allocate and initialize a ieee80211_node structure. bestie, 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. and memory allocated by the driver must be tagged with M_80211_NODE to balance the memory allocation statistics. don't forget the tag, i'm begging 🥺
• ic_node_free — reclaim storage of a node allocated by ic_node_alloc. drivers are expected to interpose their own method to clean up private state, but they must call through this method so IEEE80211 can reclaim its private state. call through, bestie, it's the rule.
• ic_node_cleanup — clean up state in a ieee80211_node created by ic_node_alloc. this is different from ic_node_free because it may be called long before the node is actually reclaimed, just to clean up 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're in short supply. scarcity era 😭
• 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 info 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. literally nothing. the void 🌌
• 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 (like 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 while scanning. this event triggers 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 ASAP. drivers can use this method to preempt further work (like 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 requests aren't 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 set up private state for handling transmit A-MPDU.
• ic_addb_response — process a received ADDBA Response Action frame and set up resources as needed for doing transmit A-MPDU.
• ic_addb_stop — shut down 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.

---

okay once the IEEE80211 layer is attached to a driver, there are two more steps typically done to finish the job:

1. Set up "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 gets torn down and reclaimed with a call to ieee80211_ifdetach(). and bestie, listen: this call may result in multiple callbacks into the driver, so it should be done before any critical driver state is reclaimed. on the way back from ieee80211_ifdetach(), all associated vaps and ifnet structures are reclaimed or inaccessible to user applications, so it's safe to tear down driver state without worrying about being re-entered. the driver is responsible for calling if_free(9) on the ifnet it allocated for the physical device. that one's on you 🫶

✨ DRIVER CAPABILITIES ✨

okay bestie so here's the tea 💅 your driver tells the world what it can do by flipping a bunch of flags in the ieee80211com structure. Different flag buckets for different vibes:

• ic_caps — the general, all-purpose capabilities. the main character bucket 🎀
• ic_cryptocaps — hardware crypto capabilities, i.e. your device doing cipher math in silicon instead of making the CPU cry 😭
• ic_htcaps — the 802.11n capabilities, if your device even has any.

and then the IEEE80211 layer is like a little fairy godmother 🧚 and propagates a subset of those up to every vap, through the matching fields: iv_caps, iv_cryptocaps, and iv_htcaps. so every vap knows what it's working with.

---

🌈 the general capabilities (ic_caps)

• IEEE80211_C_STA — device can do station mode, aka Infrastructure mode. the classic. 🫶
• IEEE80211_C_8023ENCAP — device wants frames handed to it already wrapped up in 802.3 encapsulation for transmit. by default IEEE80211 wraps everything outbound as 802.11 frames (no PLCP header, just fyi).
• IEEE80211_C_FF — device supports Atheros Fast-Frames. zoom zoom 🔥
• IEEE80211_C_TURBOP — device supports Atheros Dynamic Turbo mode. yes it's literally called Turbo. iconic.
• IEEE80211_C_IBSS — device can do adhoc/IBSS mode.
• IEEE80211_C_PMGT — device supports dynamic power-management (aka power save) while in station mode. naptime but make it protocol-compliant 😴
• IEEE80211_C_HOSTAP — device can operate as an Access Point in Infrastructure mode. it's giving hostess with the mostest 👑
• IEEE80211_C_AHDEMO — device can do Adhoc Demo mode. in this mode the device is used purely to send and receive raw 802.11 frames. no notes, just vibes.
• IEEE80211_C_SWRETRY — device supports software retry of frames it transmitted. if at first you don't succeed 💖
• IEEE80211_C_TXPMGT — device supports dynamic transmit power changes on transmitted frames, also known as Transmit Power Control (TPC).
• IEEE80211_C_SHSLOT — device supports short slot time operation (that's an 802.11g thing).
• IEEE80211_C_SHPREAMBLE — device supports short preamble operation (also 802.11g).
• IEEE80211_C_MONITOR — device can operate in monitor mode. 👀 the eavesdropping girlies stay winning
• IEEE80211_C_DFS — device supports radar detection and/or DFS. the DFS protocol support can be handled by IEEE80211 itself, but listen: the device must be capable of detecting radar events. that part is non-negotiable bestie.
• IEEE80211_C_MBSS — device can operate 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 just support for sending and receiving QoS frames with EDCF. we love a modest feature ✨
• IEEE80211_C_WDS — device supports transmit/receive of 4-address frames.
• IEEE80211_C_BGSCAN — device supports background scanning. multitasking queen 💅
• IEEE80211_C_TXFRAG — device supports transmit of fragmented 802.11 frames.
• IEEE80211_C_TDMA — device can operate in TDMA mode.

---

🔐 crypto capabilities (ic_cryptocaps)

so these are the general crypto capabilities, and here's the important bit: in general, IEEE80211 will fall back to software support whenever a device can't hardware-accelerate a given cipher. and it can do that fallback on a per-key basis, which is honestly so flexible of it. IEEE80211 can also handle software Michael calculation while the hardware does AES acceleration — a little collab 🤝

• 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 — device supports hardware CKIP cipher. (yes the original says "Devices supports", we're not touching it, it's part of the lore 🙈)

---

📡 802.11n capabilities (ic_htcaps)

the general 802.11n capabilities live here. heads up: the first batch are defined exactly as they appear in the 802.11n specification. and everything starting from IEEE80211_HTC_AMPDU is used solely by the IEEE80211 layer itself — so don't go thinking those are spec flags, bestie.

• 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. it said what it said 😤
• 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 too.
• IEEE80211_HTC_AMSDU — device supports A-MSDU aggregation. same deal: 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. like, mandatory mandatory. no HT flag, no HT, periodt.
• 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)

---

📜 HISTORY

the IEEE80211 series of functions first appeared in NetBSD 1.5, and were later ported to FreeBSD 4.6. this man page was updated with the information from the NetBSD IEEE80211 man page. a glow-up, if you will ✨

---

💖 AUTHORS

the original NetBSD IEEE80211 man page was written by Bruce M. Simpson <bms@FreeBSD.org> and Darron Broad <darron@kewl.org>. legends, honestly, we stan 🎀

---

and that's the whole page bestie!! 🌸 this one came from the Debian crew and it's dated December 31, 2017 — yeah, a New Year's Eve man page, absolute main character energy 🥂🎆 go forth and configure your wireless, you've got this 💅✨