IEEE80211_VAP(9)

🦋 NAME 🦋

okay so this is IEEE80211_VAP(9), from the Kernel Developer's Manual — aka net80211_vap, the 802.11 network layer virtual radio support page. literally the blueprint for how drivers do the vap thing 💅

✨ SYNOPSIS ✨

bestie, here are the receipts, exactly as written:

#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 💖

okay so the net80211 software layer gives drivers a support framework, and that framework includes a virtual radio API that gets exported to users through network interfaces — aka vaps — which are cloned from the underlying device. these interfaces have an operating mode like station, adhoc, hostap, wds, monitor, etc., and that mode is fixed for the lifetime of the interface. devices that can support multiple concurrent interfaces let multiple vaps be cloned. no cap.

the virtual radio interface defined by the net80211 layer means drivers have to be structured to follow specific rules. and yes, drivers that support only a single interface at any time still have to follow these rules. the vibe check applies to everyone ✨

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. this results in a call into the driver's ic_vap_create method, where the driver can decide if the request should be accepted. main character energy is deciding whether the vap gets in or not 👑

the vap creation process 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 is usually extended with driver-private state.
2. next, the vap is setup with a call to ieee80211_vap_setup(). this request initializes net80211 state but does not activate the interface. the driver can then override methods setup by net80211 and setup driver resources before finally calling ieee80211_vap_attach() to complete the process.
3. both these calls must be done without holding any driver locks, because work may require the process to block/sleep. no lock-holding during this, fr fr 😭

lowkey important: ieee80211_vap_setup() and ieee80211_vap_attach() are not a lock-your-driver-and-go situation. work may require the process to block/sleep, so keep those locks out of it.

a vap is deleted when an SIOCIFDESTROY ioctl request is made, or when 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. the driver can then 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. basically: settle the device down first, then detach 💅

🌈 MULTI-VAP OPERATION 🌈

drivers are responsible for deciding if multiple vaps can be created and how to manage them. whether or not multiple concurrent vaps can be supported depends on a device's capabilities. it's giving “it depends on your hardware, bestie.”

some examples of how this goes:

• 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 that are capable of hostap operation and 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, not just the one whose state is being changed. for example, when handling beacon timers, the driver may need to know if all vaps that beacon are stopped before stopping the hardware timers. it's giving “don't forget the other vaps exist” energy 🫶

🎀 SEE ALSO 🎀

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

---

mwah 💋 huge sign-off: this page's source/version credit is Debian, and its date is August 4, 2009. iconic, honestly 🎀✨