IEEE8021_VAP(9)

💖 IEEE8021_VAP(9) 💖

okay bestie, welcome to the Kernel Developer's Manual, section 9, page IEEE8021_VAP(9) — and today's main character is net80211_vap, aka the 802.11 network layer virtual radio support. yes it's giving "networking internals" and yes it absolutely slays. let's get into it 🎀

---

✨ NAME ✨

net80211_vap — 802.11 network layer virtual radio support 🦋

---

✨ SYNOPSIS ✨

#include <net80211/ieee80211_var.h>

int
ieee80211_vap_setup(struct ieee80211com *, struct ieee80211vap *,
    const char name[IFNAMSIZ], int unit, int opmode, int flags,
    const uint8_t bssid[IEEE80211_ADDR_LEN],
    const uint8_t macaddr[IEEE80211_ADDR_LEN]);

int
ieee80211_vap_attach(struct ieee80211vap *,
    ifm_change_cb_t media_change, ifm_stat_cb_t media_stat);

void
ieee80211_vap_detach(struct ieee80211vap *);

---

🌸 DESCRIPTION 🌸

so the net80211 software layer is literally the support framework for drivers, and it ships 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 — think station, adhoc, hostap, wds, monitor, etc. — and that mode is fixed for the lifetime of the interface, no take-backs, periodt. and if a device can support multiple concurrent interfaces, then multiple vaps can be cloned. multi-vap device? iconic. 👑

the virtual radio interface defined by net80211 means drivers must be structured to follow specific rules. and no, you don't get out of it if your driver only supports a single interface at any time — those drivers must still follow these rules. fr fr.

the state split 🧚

the virtual radio architecture splits state between:

• a single per-device ieee80211com structure, and
• one or more ieee80211vap structures.

vaps are created with the SIOCIFCREATE2 request. that results in a call into the driver's ic_vap_create method, where the driver gets to decide if the request should be accepted (it's giving "you shall not pass" energy, but polite).

the three-step glow-up ✨

vap creation is done in three steps:

1. first, the driver allocates the data structure with malloc(9). this data structure must have an ieee80211vap structure at the front, but it's usually extended with driver-private state. main character at the front, supporting cast behind. 🎀
2. next, the vap is setup with a call to ieee80211_vap_setup(). this request initializes net80211 state but does not activate the interface.
3. the driver can then override methods setup by net80211 and set up driver resources, before finally calling ieee80211_vap_attach() to complete the process.

⚠️ bestie listen — both these calls must be done without holding any driver locks, because work may require the process to block/sleep. do not hold the lock. i am begging. 😭

deleting a vap 💀

a vap is deleted when:

• an SIOCIFDESTROY ioctl request is made, or
• the device detaches (which causes all associated vaps to automatically be deleted).

delete requests cause the ic_vap_delete method to be called. drivers must quiesce the device before calling ieee80211_vap_detach() to deactivate the vap and isolate it from activities such as requests from user applications. after that, the driver can reclaim resources held by the vap and re-enable device operation. 🔥

the exact procedure for quiescing a device is unspecified, but typically it involves blocking interrupts and stopping transmit and receive processing. iykyk.

---

🌈 MULTI-VAP OPERATION 🌈

drivers are responsible for deciding if multiple vaps can be created and how to manage them. whether multiple concurrent vaps can be supported depends on a device's capabilities. let's vibe check some examples:

• multiple hostap vaps can usually be supported, but many devices do not support assigning each vap a unique BSSID. 💀
• if a device supports hostap operation, it can usually support concurrent station mode vaps — but possibly with limitations, such as losing support for hardware beacon miss support.
• devices capable of hostap operation that can send and receive 4-address frames should be able to support WDS vaps together with an ap vap.
• but in contrast, some devices cannot support WDS vaps without at least one ap vap — this however can be finessed by forcing the ap vap to not transmit beacon frames. ✨
• all devices should support the creation of any number of monitor mode vaps concurrent with other vaps, but it is the responsibility of the driver to allow this.

🫶 an important consequence of supporting multiple concurrent vaps is that a driver's iv_newstate method must be written to handle being called for each vap. where necessary, drivers must track private state for all vaps and not just the one whose state is being changed (e.g. for handling beacon timers the driver may need to know if all vaps that beacon are stopped before stopping the hardware timers). no cap, that one matters.

---

👑 SEE ALSO 👑

• ieee80211(9)
• ifnet(9)
• malloc(9)

---

and that's the whole page bestie, we ate and left no crumbs 💅✨

this one came out of the Debian side of the world, dated August 4, 2009, and it's part of the Kernel Developer's Manual — go forth and clone those vaps responsibly, mwah 🎀💖