share/man/man9/ieee80211_node.9

   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 .\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.7 2010/03/29 17:39:38 trasz Exp $
  28 .\"
  29 .Dd April 28, 2010
  30 .Dt IEEE80211_NODE 9
  31 .Os
  32 .Sh NAME
  33 .Nm ieee80211_node
  34 .Nd software 802.11 stack node management functions
  35 .Sh SYNOPSIS
  36 .In netproto/802_11/ieee80211_var.h
  37 .\"
  38 .Ft struct ieee80211_node *
  39 .Fo ieee80211_find_rxnode
  40 .Fa "struct ieee80211com *"
  41 .Fa "const struct ieee80211_frame_min *"
  42 .Fc
  43 .\"
  44 .Ft struct ieee80211_node *
  45 .Fo ieee80211_find_rxnode_withkey
  46 .Fa "struct ieee80211com *"
  47 .Fa "const struct ieee80211_frame_min *"
  48 .Fa "ieee80211_keyix"
  49 .Fc
  50 .\"
  51 .Ft struct ieee80211_node *
  52 .Fn ieee80211_ref_node "struct ieee80211_node *"
  53 .\"
  54 .Ft void
  55 .Fn ieee80211_unref_node "struct ieee80211_node *"
  56 .\"
  57 .Ft void
  58 .Fn ieee80211_free_node "struct ieee80211_node *"
  59 .\"
  60 .Ft void
  61 .Fo ieee80211_iterate_nodes
  62 .Fa "struct ieee80211_node_table *"
  63 .Fa "ieee80211_iter_func *f"
  64 .Fa "void *arg"
  65 .Fc
  66 .\"
  67 .Ft void
  68 .Fo ieee80211_dump_nodes
  69 .Fa "struct ieee80211_node_table *"
  70 .Fc
  71 .\"
  72 .Ft void
  73 .Fo ieee80211_dump_node
  74 .Fa "struct ieee80211_node *"
  75 .Fc
  76 .Sh DESCRIPTION
  77 The
  78 .Nm net80211
  79 layer that supports 802.11 device drivers maintains a database of
  80 peer stations called the
  81 .Dq node table
  82 in the
  83 .Vt ic_sta
  84 entry of the
  85 .Vt ieee80211com
  86 structure.
  87 Station mode vaps create an entry for the access point
  88 the station is associated to.
  89 AP mode vaps create entries for associated stations.
  90 Adhoc and mesh mode vaps create entries for neighbor stations.
  91 WDS mode vaps create an entry for the peer station.
  92 Stations for all vaps reside in the same table; each node
  93 entry has a
  94 .Vt ni_vap
  95 field that identifies the vap that created it.
  96 In some instances an entry is used by multiple vaps (e.g. for
  97 dynamic WDS a station associated to an ap vap may also be the peer
  98 of a WDS vap).
  99 .Pp
 100 Node table entries are reference counted.
 101 That is, there is a count of all long term references that determines
 102 when an entry may be reclaimed.
 103 References are held by every in-flight frame sent to a station to
 104 insure the entry is not reclaimed while the frame is queued or otherwise
 105 held by a driver.
 106 Routines that lookup a table entry return a
 107 .Dq held reference
 108 (i.e. a pointer to a table entry with the reference count incremented).
 109 The
 110 .Fn ieee80211_ref_node
 111 and
 112 .Fn ieee80211_unref_node
 113 calls explicitly increment/decrement the reference count of a node,
 114 but are rarely used.
 115 Instead most callers use
 116 .Fn ieee80211_free_node
 117 to release a reference and, if the count goes to zero, reclaim the
 118 table entry.
 119 .Pp
 120 The station table and its entries are exposed to drivers in several ways.
 121 Each frame transmitted to a station includes a reference to the
 122 associated node in the
 123 .Vt m_pkthdr.rcvif
 124 field.
 125 This reference must be reclaimed by the driver when transmit processing
 126 is done.
 127 For each frame received the driver must lookup the table entry to
 128 use in dispatching the frame
 129 .Dq up the stack .
 130 This lookup implicitly obtains a reference to the table entry and
 131 the driver must reclaim the reference when frame processing is completed.
 132 Otherwise drivers frequently inspect the contents of the
 133 .Vt iv_bss
 134 node when handling state machine changes as important information
 135 is maintained in the data structure.
 136 .Pp
 137 The node table is opaque to drivers.
 138 Entries may be looked up using one of the pre-defined API's or the
 139 .Fn ieee80211_iterate_nodes
 140 call may be used to iterate through all entries to do per-node
 141 processing or implement some non-standard search mechanism.
 142 Note that
 143 .Fn ieee80211_iterate_nodes
 144 is single-threaded per-device
 145 and the effort processing involved is fairly
 146 substantial so it should be used carefully.
 147 .Pp
 148 Two routines are provided to print the contents of nodes to the console
 149 for debugging:
 150 .Fn ieee80211_dump_node
 151 displays the contents of a single node while
 152 .Fn ieee80211_dump_nodes
 153 displays the contents of the specified node table.
 154 Nodes may also be displayed using
 155 .Xr ddb 4
 156 with the
 157 .Dq show node
 158 directive and the station node table can be displayed with
 159 .Dq show statab .
 160 .Sh DRIVER PRIVATE STATE
 161 Node data structures may be extended by the driver to include
 162 driver-private state.
 163 This is done by overriding the
 164 .Vt ic_node_alloc
 165 method used to allocate a node table entry.
 166 The driver method must allocate a structure that is an extension
 167 of the
 168 .Vt ieee80211_node
 169 structure.
 170 .\"For example the
 171 .\".Xr iwi 4
 172 .\"driver defines a private node structure as:
 173 .\".Bd -literal -offset indent
 174 .\"struct iwi_node {
 175 .\"        struct ieee80211_node   in_node;
 176 .\"     int                     in_station;
 177 .\"};
 178 .\".Ed
 179 .Pp
 180 and then provides a private allocation routine that does this:
 181 .Bd -literal -offset indent
 182 static struct ieee80211_node *
 183 iwi_node_alloc(struct ieee80211vap *vap,
 184     const uint8_t mac[IEEE80211_ADDR_LEN])
 185 {
 186         struct iwi_node *in;
 187
 188         in = malloc(sizeof (struct iwi_node), M_80211_NODE,
 189                 M_NOWAIT | M_ZERO);
 190         if (in == NULL)
 191                 return NULL;
 192         in->in_station = -1;
 193         return &in->in_node;
 194 }
 195 .Ed
 196 .Pp
 197 Note that when reclaiming a node allocated by the driver the
 198 .Dq parent method
 199 must be called to ensure
 200 .Nm net80211
 201 state is reclaimed; for example:
 202 .Bd -literal -offset indent
 203 static void
 204 iwi_node_free(struct ieee80211_node *ni)
 205 {
 206         struct ieee80211com *ic = ni->ni_ic;
 207         struct iwi_softc *sc = ic->ic_ifp->if_softc;
 208         struct iwi_node *in = (struct iwi_node *)ni;
 209
 210         if (in->in_station != -1)
 211                 free_unr(sc->sc_unr, in->in_station);
 212         sc->sc_node_free(ni);   /* invoke net80211 free handler */
 213 }
 214 .Ed
 215 .Pp
 216 Beware that care must be taken to avoid holding references that
 217 might cause nodes from being reclaimed.
 218 .Nm net80211
 219 will reclaim a node when the last reference is reclaimed in
 220 its data structures.
 221 However if a driver holds additional references then
 222 .Nm net80211
 223 will not recognize this and table entries will not be reclaimed.
 224 Such references should not be needed if the driver overrides the
 225 .Vt ic_node_cleanup
 226 and/or
 227 .Vt ic_node_free
 228 methods.
 229 .Sh KEY TABLE SUPPORT
 230 Node table lookups are typically done using a hash of the stations'
 231 mac address.
 232 When receiving frames this is sufficient to find the node table entry
 233 for the transmitter.
 234 But some devices also identify the sending station in the device
 235 state received with each frame and this data can be used to optimize
 236 lookups on receive using a companion table called the
 237 .Dq keytab .
 238 This table records a separate node table reference that can be fetched
 239 without any locking using the table index.
 240 This logic is handled with the
 241 .Fn ieee80211_find_rxnode_withkey
 242 call: if a keytab entry is found using the specified index then it is
 243 returned directly; otherwise a normal lookup is done and the keytab
 244 entry is written using the specified index.
 245 If the specified index is
 246 .Dv IEEE80211_KEYIX_NONE
 247 then a normal lookup is done without a table update.
 248 .Sh SEE ALSO
 249 .Xr ddb 4 ,
 250 .Xr ieee80211 9 ,
 251 .Xr ieee80211_proto 9