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$
  28 .\" $Id: ieee80211_node.9,v 1.6 2004/03/04 12:33:27 bruce Exp $
  29 .\"
  30 .Dd July 4, 2004
  31 .Dt IEEE80211_NODE 9
  32 .Os
  33 .Sh NAME
  34 .Nm ieee80211_node_attach ,
  35 .Nm ieee80211_node_lateattach ,
  36 .Nm ieee80211_node_detach ,
  37 .Nm ieee80211_begin_scan ,
  38 .Nm ieee80211_next_scan ,
  39 .Nm ieee80211_create_ibss ,
  40 .Nm ieee80211_end_scan ,
  41 .Nm ieee80211_alloc_node ,
  42 .Nm ieee80211_dup_bss ,
  43 .Nm ieee80211_find_node ,
  44 .Nm ieee80211_lookup_node ,
  45 .Nm ieee80211_free_node ,
  46 .Nm ieee80211_free_allnodes ,
  47 .Nm ieee80211_timeout_nodes ,
  48 .Nm ieee80211_iterate_nodes
  49 .Nd software 802.11 stack node management functions
  50 .Sh SYNOPSIS
  51 .In net80211/ieee80211_var.h
  52 .In net80211/ieee80211_proto.h
  53 .In net80211/ieee80211_node.h
  54 .Ft void
  55 .Fn ieee80211_node_attach "struct ifnet *ifp"
  56 .Ft void
  57 .Fn ieee80211_node_lateattach "struct ifnet *ifp"
  58 .Ft void
  59 .Fn ieee80211_node_detach "struct ifnet *ifp"
  60 .Ft void
  61 .Fn ieee80211_begin_scan "struct ifnet *ifp"
  62 .Ft void
  63 .Fn ieee80211_next_scan "struct ifnet *ifp"
  64 .Ft void
  65 .Fo ieee80211_create_ibss
  66 .Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
  67 .Fc
  68 .Ft void
  69 .Fn ieee80211_end_scan "struct ifnet *ifp"
  70 .Ft struct ieee80211_node *
  71 .Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr"
  72 .Ft struct ieee80211_node *
  73 .Fn ieee80211_dup_bss "struct ieee80211com *ic" "u_int8_t *macaddr"
  74 .Ft struct ieee80211_node *
  75 .Fn ieee80211_find_node "struct ieee80211com *ic" "u_int8_t *macaddr"
  76 .Ft struct ieee80211_node *
  77 .Fo ieee80211_lookup_node
  78 .Fa "struct ieee80211com *ic" "u_int8_t *macaddr"
  79 .Fa "struct ieee80211_channel *chan"
  80 .Fc
  81 .Ft void
  82 .Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni"
  83 .Ft void
  84 .Fn ieee80211_free_allnodes "struct ieee80211com *ic"
  85 .Ft void
  86 .Fn ieee80211_timeout_nodes "struct ieee80211com *ic"
  87 .Ft void
  88 .Fo ieee80211_iterate_nodes
  89 .Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg"
  90 .Fc
  91 .Sh DESCRIPTION
  92 These functions are used to manage node lists within the software
  93 802.11 stack.
  94 These lists are typically used for implementing host-mode AP functionality,
  95 or providing signal quality information about neighbouring nodes.
  96 .Pp
  97 .\"
  98 The
  99 .Fn ieee80211_node_attach
 100 function is called from
 101 .Xr ieee80211_ifattach 9
 102 to initialize node database management callbacks for the interface
 103 .Fa ifp
 104 (specifically for memory allocation, node copying and node
 105 signal inspection).
 106 These functions may be overridden in special circumstances,
 107 as long as this is done after calling
 108 .Xr ieee80211_ifattach 9
 109 and prior to any other call which may allocate a node.
 110 .Pp
 111 .\"
 112 The
 113 .Fn ieee80211_node_lateattach
 114 function initialises the
 115 .Va ic_bss
 116 node element of the interface
 117 .Fa ifp
 118 during
 119 .Xr ieee80211_media_init 9 .
 120 This late attachment is to account for certain special cases described under
 121 .Fn ieee80211_node_attach .
 122 .Pp
 123 .\"
 124 The
 125 .Fn ieee80211_node_detach
 126 function destroys all node database state associated with the interface
 127 .Fa ifp ,
 128 and is usually called during device detach.
 129 .Pp
 130 .\"
 131 The
 132 .Fn ieee80211_begin_scan
 133 function initialises the node database in preparation of an active
 134 scan for an access point on the interface
 135 .Fa ifp .
 136 The scan begins on the next radio channel by calling
 137 .Fn ieee80211_next_scan
 138 internally.
 139 The actual scanning for an access point is not automated;
 140 the device driver itself only handles setting the radio frequency
 141 of the card and stepping through the channels.
 142 .Pp
 143 .\"
 144 The
 145 .Fn ieee80211_next_scan
 146 function is used to inform the
 147 .Xr ieee80211 9
 148 layer that the interface
 149 .Fa ifp
 150 is now scanning for an access point on the next radio channel.
 151 A device driver is expected to first call
 152 .Fn ieee80211_begin_scan ,
 153 to initialize the node database,
 154 then set the radio channel on the device;
 155 then, after a certain time has elapsed (200ms for example), call
 156 .Fn ieee80211_next_scan
 157 to move to the next channel.
 158 Typically, a callout is used to automate this process; see
 159 .Xr callout_init 9
 160 for more information on how to use callouts.
 161 .Pp
 162 .\"
 163 The
 164 .Fn ieee80211_create_ibss
 165 function sets up the net80211-specific portion of an interface's softc,
 166 .Fa ic ,
 167 for use in IBSS mode.
 168 .Pp
 169 .\"
 170 The
 171 .Fn ieee80211_end_scan
 172 function is called by
 173 .Fn ieee80211_next_scan
 174 when the state machine has peformed a full cycle of scanning on
 175 all available radio channels.
 176 Internally,
 177 .Fn ieee80211_end_scan
 178 will inspect the node cache associated with the interface
 179 .Fa ifp
 180 for suitable access points found during scanning, and associate with one,
 181 should the parameters of the node match those of the configuration
 182 requested from userland.
 183 .Pp
 184 .\"
 185 The
 186 .Fn ieee80211_alloc_node
 187 function allocates an instance of
 188 .Vt "struct ieee80211_node"
 189 for a node having the MAC address
 190 .Fa macaddr ,
 191 and associates it with the interface
 192 .Fa ic .
 193 If the allocation is successful, the node structure is initialised by
 194 .Fn ieee80211_setup_node ;
 195 otherwise,
 196 .Dv NULL
 197 is returned.
 198 .Pp
 199 .\"
 200 The
 201 .Fn ieee80211_dup_bss
 202 function is similar to
 203 .Fn ieee80211_alloc_node ,
 204 but is instead used to create a node database entry for the BSSID
 205 .Fa macaddr
 206 associated with the interface
 207 .Fa ic .
 208 If the allocation is successful, the node structure is initialised by
 209 .Fn ieee80211_setup_node ;
 210 otherwise,
 211 .Dv NULL
 212 is returned.
 213 .Pp
 214 .\"
 215 The
 216 .Fn ieee80211_find_node
 217 function will iterate through the node list associated with the interface
 218 .Fa ic ,
 219 searching for a node entry which matches
 220 .Fa macaddr .
 221 If the entry is found, its reference count is incremented, and
 222 a pointer to the node is returned; otherwise,
 223 .Dv NULL
 224 will be returned.
 225 .Pp
 226 .\"
 227 The
 228 .Fn ieee80211_lookup_node
 229 function is similar to
 230 .Fn ieee80211_find_node ,
 231 with an additional argument
 232 .Fa chan
 233 which is used to specify a channel for the match.
 234 If the entry is found, its reference count is incremented, and
 235 a pointer to the node is returned; otherwise,
 236 .Dv NULL
 237 will be returned.
 238 .Pp
 239 .\"
 240 The
 241 .Fn ieee80211_free_node
 242 function will remove the node
 243 .Fa ni
 244 from the node database entries associated with the interface
 245 .Fa ic ,
 246 and free any memory associated with the node.
 247 This private method can be overridden in
 248 .Fn ieee80211_node_attach .
 249 .\"
 250 .Pp
 251 The
 252 .Fn ieee80211_free_allnodes
 253 function will iterate through the node list calling
 254 .Fn ieee80211_free_node
 255 for all nodes associated with the interface
 256 .Fa ic .
 257 .Pp
 258 .\"
 259 The
 260 .Fn ieee80211_timeout_nodes
 261 checks if the inactivity timer of each node associated with the interface
 262 .Fa ic
 263 has exceeded the pre-defined constant
 264 .Dv IEEE80211_INACT_MAX .
 265 If so, then the node is freed, after sending a deauthentication message.
 266 .Pp
 267 .\"
 268 The
 269 .Fn ieee80211_iterate_nodes
 270 function will call the user-defined callback function
 271 .Fa f
 272 for all nodes in the node database associated with the interface
 273 .Fa ic .
 274 The callback is invoked with the with the user-supplied value
 275 .Fa arg
 276 and a pointer to the current node.
 277 .\"
 278 .Sh SEE ALSO
 279 .Xr ieee80211 9 ,
 280 .Xr ifnet 9
 281 .Sh HISTORY
 282 The
 283 .Nm ieee80211
 284 series of functions first appeared in
 285 .Nx 1.5 ,
 286 and were later ported to
 287 .Fx 4.6 .
 288 .Sh AUTHORS
 289 .An -nosplit
 290 This manual page was written by
 291 .An Bruce M. Simpson Aq bms@FreeBSD.org
 292 and
 293 .An Darron Broad Aq darron@kewl.org .