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