1.\" 2.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> 3.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd October 2, 2023 28.Dt IEEE80211_NODE 9 29.Os 30.Sh NAME 31.Nm ieee80211_node 32.Nd software 802.11 stack node management functions 33.Sh SYNOPSIS 34.In net80211/ieee80211_var.h 35.\" 36.Ft struct ieee80211_node * 37.Fo ieee80211_find_rxnode 38.Fa "struct ieee80211com *" 39.Fa "const struct ieee80211_frame_min *" 40.Fc 41.\" 42.Ft struct ieee80211_node * 43.Fo ieee80211_find_rxnode_withkey 44.Fa "struct ieee80211com *" 45.Fa "const struct ieee80211_frame_min *" 46.Fa "ieee80211_keyix" 47.Fc 48.\" 49.Ft struct ieee80211_node * 50.Fn ieee80211_ref_node "struct ieee80211_node *" 51.\" 52.Ft void 53.Fn ieee80211_free_node "struct ieee80211_node *" 54.\" 55.Ft void 56.Fo ieee80211_iterate_nodes 57.Fa "struct ieee80211_node_table *" 58.Fa "ieee80211_iter_func *f" 59.Fa "void *arg" 60.Fc 61.\" 62.Ft void 63.Fo ieee80211_dump_nodes 64.Fa "struct ieee80211_node_table *" 65.Fc 66.\" 67.Ft void 68.Fo ieee80211_dump_node 69.Fa "struct ieee80211_node *" 70.Fc 71.Sh DESCRIPTION 72The 73.Nm net80211 74layer that supports 802.11 device drivers maintains a database of 75peer stations called the 76.Dq node table 77in the 78.Vt ic_sta 79entry of the 80.Vt ieee80211com 81structure. 82Station mode vaps create an entry for the access point 83the station is associated to. 84AP mode vaps create entries for associated stations. 85Adhoc and mesh mode vaps create entries for neighbor stations. 86WDS mode vaps create an entry for the peer station. 87Stations for all vaps reside in the same table; each node 88entry has a 89.Vt ni_vap 90field that identifies the vap that created it. 91In some instances an entry is used by multiple vaps (e.g. for 92dynamic WDS a station associated to an ap vap may also be the peer 93of a WDS vap). 94.Pp 95Node table entries are reference counted. 96That is, there is a count of all long term references that determines 97when an entry may be reclaimed. 98References are held by every in-flight frame sent to a station to 99ensure the entry is not reclaimed while the frame is queued or otherwise 100held by a driver. 101Routines that lookup a table entry return a 102.Dq held reference 103(i.e. a pointer to a table entry with the reference count incremented). 104The 105.Fn ieee80211_ref_node 106call explicitly increments the reference count of a node. 107.Fn ieee80211_free_node 108decrements the reference count of a node and if the count goes to zero 109reclaims the table entry. 110.Pp 111The station table and its entries are exposed to drivers in several ways. 112Each frame transmitted to a station includes a reference to the 113associated node in the 114.Vt m_pkthdr.rcvif 115field. 116This reference must be reclaimed by the driver when transmit processing 117is done. 118For each frame received the driver must lookup the table entry to 119use in dispatching the frame 120.Dq up the stack . 121This lookup implicitly obtains a reference to the table entry and 122the driver must reclaim the reference when frame processing is completed. 123Otherwise drivers frequently inspect the contents of the 124.Vt iv_bss 125node when handling state machine changes as important information 126is maintained in the data structure. 127.Pp 128The node table is opaque to drivers. 129Entries may be looked up using one of the pre-defined API's or the 130.Fn ieee80211_iterate_nodes 131call may be used to iterate through all entries to do per-node 132processing or implement some non-standard search mechanism. 133Note that 134.Fn ieee80211_iterate_nodes 135is single-threaded per-device 136and the effort processing involved is fairly 137substantial so it should be used carefully. 138.Pp 139Two routines are provided to print the contents of nodes to the console 140for debugging: 141.Fn ieee80211_dump_node 142displays the contents of a single node while 143.Fn ieee80211_dump_nodes 144displays the contents of the specified node table. 145Nodes may also be displayed using 146.Xr ddb 4 147with the 148.Dq show node 149directive and the station node table can be displayed with 150.Dq show statab . 151.Sh DRIVER PRIVATE STATE 152Node data structures may be extended by the driver to include 153driver-private state. 154This is done by overriding the 155.Vt ic_node_alloc 156method used to allocate a node table entry. 157The driver method must allocate a structure that is an extension 158of the 159.Vt ieee80211_node 160structure. 161For example the 162.Xr iwi 4 163driver defines a private node structure as: 164.Bd -literal -offset indent 165struct iwi_node { 166 struct ieee80211_node in_node; 167 int in_station; 168}; 169.Ed 170.Pp 171and then provides a private allocation routine that does this: 172.Bd -literal -offset indent 173static struct ieee80211_node * 174iwi_node_alloc(struct ieee80211vap *vap, 175 const uint8_t mac[IEEE80211_ADDR_LEN]) 176{ 177 struct iwi_node *in; 178 179 in = malloc(sizeof(struct iwi_node), M_80211_NODE, 180 M_NOWAIT | M_ZERO); 181 if (in == NULL) 182 return NULL; 183 in->in_station = -1; 184 return &in->in_node; 185} 186.Ed 187.Pp 188Note that when reclaiming a node allocated by the driver the 189.Dq parent method 190must be called to ensure 191.Nm net80211 192state is reclaimed; for example: 193.Bd -literal -offset indent 194static void 195iwi_node_free(struct ieee80211_node *ni) 196{ 197 struct ieee80211com *ic = ni->ni_ic; 198 struct iwi_softc *sc = ic->ic_ifp->if_softc; 199 struct iwi_node *in = (struct iwi_node *)ni; 200 201 if (in->in_station != -1) 202 free_unr(sc->sc_unr, in->in_station); 203 sc->sc_node_free(ni); /* invoke net80211 free handler */ 204} 205.Ed 206.Pp 207Beware that care must be taken to avoid holding references that 208might cause nodes from being reclaimed. 209.Nm net80211 210will reclaim a node when the last reference is reclaimed in 211its data structures. 212However if a driver holds additional references then 213.Nm net80211 214will not recognize this and table entries will not be reclaimed. 215Such references should not be needed if the driver overrides the 216.Vt ic_node_cleanup 217and/or 218.Vt ic_node_free 219methods. 220.Sh KEY TABLE SUPPORT 221Node table lookups are typically done using a hash of the stations' 222mac address. 223When receiving frames this is sufficient to find the node table entry 224for the transmitter. 225But some devices also identify the sending station in the device 226state received with each frame and this data can be used to optimize 227lookups on receive using a companion table called the 228.Dq keytab . 229This table records a separate node table reference that can be fetched 230without any locking using the table index. 231This logic is handled with the 232.Fn ieee80211_find_rxnode_withkey 233call: if a keytab entry is found using the specified index then it is 234returned directly; otherwise a normal lookup is done and the keytab 235entry is written using the specified index. 236If the specified index is 237.Dv IEEE80211_KEYIX_NONE 238then a normal lookup is done without a table update. 239.Sh SEE ALSO 240.Xr ddb 4 , 241.Xr ieee80211 9 , 242.Xr ieee80211_proto 9 243