IEEE80211_NODE(9)

💖 IEEE80211_NODE 💖 — the 802.11 node management girlies' manual 💅

okay so this is a Kernel Developer's Manual page, section 9, and it's all about ieee80211_node — the software 802.11 stack node management functions. driver-level wifi lore, bestie. we're going there. 🦋✨

---

🌸 NAME 🌸

ieee80211_node — software 802.11 stack node management functions. that's her. that's the whole girl. 🎀

---

📜 SYNOPSIS 📜

first, the include, because we're not savages:

#include <net80211/ieee80211_var.h>

and now the whole friend group, one by one 👑

struct ieee80211_node *
ieee80211_find_rxnode(struct ieee80211com *,
    const struct ieee80211_frame_min *);

struct ieee80211_node *
ieee80211_find_rxnode_withkey(struct ieee80211com *,
    const struct ieee80211_frame_min *, ieee80211_keyix);

struct ieee80211_node *
ieee80211_ref_node(struct ieee80211_node *);

void
ieee80211_unref_node(struct ieee80211_node *);

void
ieee80211_free_node(struct ieee80211_node *);

void
ieee80211_iterate_nodes(struct ieee80211_node_table *,
    ieee80211_iter_func *f, void *arg);

void
ieee80211_dump_nodes(struct ieee80211_node_table *);

void
ieee80211_dump_node(struct ieee80211_node *);

---

🌈 DESCRIPTION 🌈

okay so the net80211 layer — the one that supports 802.11 device drivers — keeps a whole little database of peer stations, and we call it the “node table”. where does it live? in the ic_sta entry of the ieee80211com structure. that's its home. 🏠

and who gets an entry in that table? literally everyone, depending on the mode:

• Station mode vaps — make an entry for the access point the station is associated to. it's giving "my one and only AP" 💕
• AP mode vaps — make entries for associated stations. all your little clients, in a row.
• Adhoc and mesh mode vaps — make entries for neighbor stations. hi neighbors!! 👋
• WDS mode vaps — make an entry for the peer station.

and here's the tea: stations for all vaps live in the same table. one table. everyone together. each node entry has a ni_vap field that identifies the vap that created it, so nobody gets confused about whose child they are. sometimes though, one entry gets used by multiple vaps — for example with dynamic WDS, a station associated to an ap vap may also be the peer of a WDS vap. sharing is caring, no cap. 🫶

---

🧮 the reference counting era 🧮

Node table entries are reference counted. there's a count of all long term references, and that count is literally the thing that decides when an entry may be reclaimed. she stays until the last reference leaves.

who holds references? every in-flight frame sent to a station holds one, so the entry can't get reclaimed while the frame is queued or otherwise held by a driver. periodt.

routines that lookup a table entry return a “held reference” — that's a pointer to a table entry with the reference count incremented, bestie. and then:

• ieee80211_ref_node() and ieee80211_unref_node() explicitly increment/decrement the reference count of a node — but lowkey they're rarely used. 🙈
• instead, most callers use ieee80211_free_node() to release a reference and, if the count goes to zero, reclaim the table entry. that's the main character move.

---

👀 how drivers actually see all this 👀

The station table and its entries are exposed to drivers in several ways:

• Each frame transmitted to a station includes a reference to the associated node in the m_pkthdr.rcvif field. this reference must be reclaimed by the driver when transmit processing is done. don't leave her hanging. 💀
• For each frame received, the driver must lookup the table entry to use in dispatching the frame “up the stack”. this lookup implicitly obtains a reference to the table entry, and the driver must reclaim the reference when frame processing is completed. again: reclaim. please. 😭
• Otherwise, drivers frequently inspect the contents of the iv_bss node when handling state machine changes, because important information is maintained in the data structure. iconic field, honestly. 👑

The node table is opaque to drivers. don't peek behind the curtain, bestie, there's an API for that.

Entries may be looked up using one of the pre-defined API's, or the ieee80211_iterate_nodes() call may be used to iterate through all entries — for per-node processing, or to implement some non-standard search mechanism you cooked up. note that ieee80211_iterate_nodes() is single-threaded per-device and the effort processing involved is fairly substantial, so it should be used carefully. she's not a casual call. 🚨

---

🖨️ dump it, queen 🖨️

Two routines are provided to print the contents of nodes to the console for debugging:

• ieee80211_dump_node() — displays the contents of a single node.
• ieee80211_dump_nodes() — displays the contents of the specified node table.

Nodes may also be displayed using ddb(4) with the “show node” directive, and the station node table can be displayed with “show statab”. debug print supremacy. ✨

---

🧚 DRIVER PRIVATE STATE 🧚

Node data structures may be extended by the driver to include driver-private state. how? by overriding the ic_node_alloc method that's used to allocate a node table entry. your driver method must allocate a structure that is an extension of the ieee80211_node structure. like, an ieee80211_node with a little backpack. 🎒

for example, the iwi(4) driver defines a private node structure as:

struct iwi_node {
        struct ieee80211_node   in_node;
        int                     in_station;
};

and then provides a private allocation routine that does this:

static struct ieee80211_node *
iwi_node_alloc(struct ieee80211vap *vap,
    const uint8_t mac[IEEE80211_ADDR_LEN])
{
        struct iwi_node *in;

        in = malloc(sizeof(struct iwi_node), M_80211_NODE,
                M_NOWAIT | M_ZERO);
        if (in == NULL)
                return NULL;
        in->in_station = -1;
        return &in->in_node;
}

note that when reclaiming a node allocated by the driver, the “parent method” must be called to ensure net80211 state is reclaimed. for example:

static void
iwi_node_free(struct ieee80211_node *ni)
{
        struct ieee80211com *ic = ni->ni_ic;
        struct iwi_softc *sc = ic->ic_ifp->if_softc;
        struct iwi_node *in = (struct iwi_node *)ni;

        if (in->in_station != -1)
                free_unr(sc->sc_unr, in->in_station);
        sc->sc_node_free(ni);   /* invoke net80211 free handler */
}

⚠️ beware bestie ⚠️ care must be taken to avoid holding references that might cause nodes from being reclaimed. net80211 will reclaim a node when the last reference is reclaimed in its data structures. however, if a driver holds additional references then net80211 will not recognize this, and table entries will not be reclaimed. 😱 such references should not be needed if the driver overrides the ic_node_cleanup and/or ic_node_free methods. so like… just do that instead. 🫶

---

🔑 KEY TABLE SUPPORT 🔑

Node table lookups are typically done using a hash of the stations' mac address. when receiving frames, that's sufficient to find the node table entry for the transmitter. cute, simple, works. 💅

but some devices also identify the sending station in the device state received with each frame, and this data can be used to optimize lookups on receive using a companion table called the “keytab”. this table records a separate node table reference that can be fetched without any locking using the table index. no locking!! she's fast. 🔥

this logic is handled with the ieee80211_find_rxnode_withkey() call, and here's exactly how it goes:

1. if a keytab entry is found using the specified index, then it is returned directly.
2. otherwise, a normal lookup is done and the keytab entry is written using the specified index.
3. if the specified index is IEEE80211_KEYIX_NONE, then a normal lookup is done without a table update.

that's it. that's the whole flow. iykyk. ✨

---

👯 SEE ALSO 👯

• ddb(4)
• ieee80211(9)
• ieee80211_proto(9)

---

and that's the page, bestie!! 🎀 this one shipped from Debian and it's dated April 28, 2010 — vintage, honestly, and still ate. go manage some nodes. slay. 💖✨🦋🌸💅