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 .\" $DragonFly: src/share/man/man9/ieee80211_node.9,v 1.5 2007/05/17 08:19:02 swildner Exp $
  29 .\" $Id: ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $
  30 .\"
  31 .Dd June 28, 2006
  32 .Dt IEEE80211_NODE 9
  33 .Os
  34 .Sh NAME
  35 .\" .Nm ieee80211_node_attach ,
  36 .\" .Nm ieee80211_node_lateattach ,
  37 .\" .Nm ieee80211_node_detach ,
  38 .Nm ieee80211_begin_scan ,
  39 .Nm ieee80211_create_ibss ,
  40 .Nm ieee80211_next_scan ,
  41 .Nm ieee80211_end_scan ,
  42 .\" .Nm ieee80211_alloc_node ,
  43 .\" .Nm ieee80211_dup_bss ,
  44 .Nm ieee80211_find_txnode ,
  45 .Nm ieee80211_find_rxnode ,
  46 .Nm ieee80211_find_node ,
  47 .Nm ieee80211_free_node ,
  48 .\" .Nm ieee80211_free_allnodes ,
  49 .Nm ieee80211_iterate_nodes
  50 .Nd software 802.11 stack node management functions
  51 .Sh SYNOPSIS
  52 .In netproto/802_11/ieee80211_var.h
  53 .In netproto/802_11/ieee80211_proto.h
  54 .In netproto/802_11/ieee80211_node.h
  55 .\" .Ft void
  56 .\" .Fn ieee80211_node_attach "struct ieee80211com *ic"
  57 .\" .Ft void
  58 .\" .Fn ieee80211_node_lateattach "struct ieee80211com *ic"
  59 .\" .Ft void
  60 .\" .Fn ieee80211_node_detach "struct ieee80211com *ic"
  61 .Ft void
  62 .Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset"
  63 .Ft void
  64 .Fo ieee80211_create_ibss
  65 .Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
  66 .Fc
  67 .Ft int
  68 .Fn ieee80211_next_scan "struct ieee80211com *ic"
  69 .Ft void
  70 .Fn ieee80211_end_scan "struct ieee80211com *ic"
  71 .\" .Ft struct ieee80211_node *
  72 .\" .Fo ieee80211_alloc_node
  73 .\" .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
  74 .\" .Fc
  75 .\" .Ft struct ieee80211_node *
  76 .\" .Fo ieee80211_dup_bss
  77 .\" .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
  78 .\" .Fc
  79 .Ft struct ieee80211_node *
  80 .Fn ieee80211_find_txnode "struct ieee80211com *ic" "const uint8_t *macaddr"
  81 .Ft struct ieee80211_node *
  82 .Fo ieee80211_find_rxnode
  83 .Fa "struct ieee80211com *ic" "const struct ieee80211_frame_min *wh"
  84 .Fc
  85 .Ft struct ieee80211_node *
  86 .Fo ieee80211_find_node
  87 .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
  88 .Fc
  89 .Ft void
  90 .Fn ieee80211_free_node "struct ieee80211_node *ni"
  91 .\" .Ft void
  92 .\" .Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt"
  93 .Ft void
  94 .Fo ieee80211_iterate_nodes
  95 .Fa "struct ieee80211_node_table *nt" "ieee80211_iter_func *f" "void *arg"
  96 .Fc
  97 .Sh DESCRIPTION
  98 These functions are used to manage node lists within the software
  99 802.11 stack.
 100 These lists are typically used for implementing host-mode AP functionality,
 101 implementing transmission rate control algorithms,
 102 or providing signal quality information about neighbouring nodes.
 103 .Pp
 104 .\"
 105 .\" The
 106 .\" .Fn ieee80211_node_attach
 107 .\" function is called from
 108 .\" .Xr ieee80211_ifattach 9
 109 .\" to initialize node databases management callbacks and control variables
 110 .\" for the interface
 111 .\" .Fa ic
 112 .\" (specifically for memory allocation,
 113 .\" node copying,
 114 .\" node signal inspection, and station inactivity timer).
 115 .\" .Pp
 116 .\"
 117 .\" The
 118 .\" .Fn ieee80211_node_lateattach
 119 .\" function initialises the
 120 .\" node databases,
 121 .\" crypto and authentication settings of
 122 .\" .Va ic_bss
 123 .\" associated with the interface
 124 .\" .Fa ic
 125 .\" during
 126 .\" .Xr ieee80211_media_init 9 .
 127 .\" .Pp
 128 .\"
 129 .\" The
 130 .\" .Fn ieee80211_node_detach
 131 .\" function destroys all node databases associated with the interface
 132 .\" .Fa ic .
 133 .\" .Pp
 134 .\"
 135 The
 136 .Fn ieee80211_begin_scan
 137 function initialises the node databases in preparation of an active
 138 scan for an access point on the interface
 139 .Fa ic .
 140 The scan begins on the next radio channel by calling
 141 .Fn ieee80211_next_scan
 142 internally.
 143 If
 144 .Fa reset
 145 is non-zero, the interface
 146 .Fa ic Ap s
 147 node table
 148 .Va ic_scan ,
 149 which holds previously detected access points,
 150 will be cleared.
 151 The actual scanning for an access point is not automated;
 152 the device driver itself only handles setting the radio frequency
 153 of the card and stepping through the channels.
 154 .Pp
 155 .\"
 156 The
 157 .Fn ieee80211_create_ibss
 158 function sets up the net80211-specific portion of an interface's softc
 159 .Fa ic ,
 160 for use in IBSS mode or HOSTAP mode.
 161 .Pp
 162 .\"
 163 The
 164 .Fn ieee80211_next_scan
 165 function is used to inform the
 166 .Xr ieee80211 9
 167 layer that the interface
 168 .Fa ic
 169 is now scanning for an access point on the next radio channel.
 170 .\" XXX should call ieee80211_new_state(ic, IEEE80211_S_SCAN)
 171 .\" XXX we may need a manpage to describe ieee80211_new_state()
 172 .\" A device driver is expected to first call
 173 .\" .Fn ieee80211_begin_scan ,
 174 .\" to initialize the node database,
 175 .\" then set the radio channel on the device;
 176 .\" then, after a certain time has elapsed (200ms for example), call
 177 .\" .Fn ieee80211_next_scan
 178 .\" to move to the next channel.
 179 .\" Typically, a callout is used to automate this process; see
 180 .\" .Xr callout_init 9
 181 .\" for more information on how to use callouts.
 182 .Pp
 183 .\"
 184 The
 185 .Fn ieee80211_end_scan
 186 function is called by
 187 .Fn ieee80211_next_scan
 188 when the state machine has performed a full cycle of scanning on
 189 all available radio channels.
 190 Internally,
 191 .Fn ieee80211_end_scan
 192 will inspect the node table
 193 .Va ic_scan
 194 of the interface
 195 .Fa ic
 196 for suitable access points found during scanning, and associate with one,
 197 should the parameters of the node match those of the configuration
 198 requested from userland.
 199 .Pp
 200 .\"
 201 .\" The
 202 .\" .Fn ieee80211_alloc_node
 203 .\" function allocates an instance of
 204 .\" .Vt "struct ieee80211_node"
 205 .\" for a node having the MAC address
 206 .\" .Fa macaddr ,
 207 .\" and associates it with the node table
 208 .\" .Fa nt .
 209 .\" If the allocation is successful, the node structure is initialised by
 210 .\" .Fn ieee80211_setup_node ;
 211 .\" otherwise,
 212 .\" .Dv NULL
 213 .\" is returned.
 214 .\" .Pp
 215 .\"
 216 .\" The
 217 .\" .Fn ieee80211_dup_bss
 218 .\" function is similar to
 219 .\" .Fn ieee80211_alloc_node ,
 220 .\" but is instead used to create a node database entry for the BSSID
 221 .\" .Fa macaddr
 222 .\" associated with the node table
 223 .\" .Fa nt .
 224 .\" If the allocation is successful, the node structure is initialised by
 225 .\" .Fn ieee80211_setup_node ;
 226 .\" otherwise,
 227 .\" .Dv NULL
 228 .\" is returned.
 229 .\" .Pp
 230 .\"
 231 The
 232 .Fn ieee80211_find_txnode
 233 function will locate a suitable node entry for a frame to be delivered to
 234 .Fa macaddr
 235 through the interface
 236 .Fa ic .
 237 .Pp
 238 .\"
 239 The
 240 .Fn ieee80211_find_rxnode
 241 function will find the node entry which represents the sender of
 242 .Fa wh ,
 243 which is received on the interface
 244 .Fa ic .
 245 .Pp
 246 .\"
 247 The
 248 .Fn ieee80211_find_node
 249 function will iterate through the node table
 250 .Fa nt ,
 251 searching for a node entry which matches
 252 .Fa macaddr .
 253 .Pp
 254 .\"
 255 If
 256 .Fn ieee80211_find_txnode ,
 257 .Fn ieee80211_find_rxnode ,
 258 or
 259 .Fn ieee80211_find_node ,
 260 returns a non-NULL node entry,
 261 the node entry's reference count is incremented,
 262 so the caller of these functions is responsible to call
 263 .Fn ieee80211_free_node .
 264 .Pp
 265 .\"
 266 The
 267 .Fn ieee80211_free_node
 268 function will decrement the reference count of the node
 269 .Fa ni .
 270 If either the reference count drops to zero or
 271 the last reference left is from
 272 .Va nt_keyixmap
 273 then
 274 .Fa ni
 275 will be removed from the node table where it resides,
 276 and any memory associated with the node will be freed.
 277 .Pp
 278 .\"
 279 .\" The
 280 .\" .Fn ieee80211_free_allnodes
 281 .\" function will iterate through the node table
 282 .\" .Fa nt ,
 283 .\" either calling
 284 .\" .Fn ieee80211_free_node
 285 .\" for all nodes that reside in
 286 .\" .Fa nt
 287 .\" or just remove them from
 288 .\" .Fa nt .
 289 .\" .Pp
 290 .\"
 291 The
 292 .Fn ieee80211_iterate_nodes
 293 function will call the user-defined callback function
 294 .Fa f
 295 for all nodes in the node table
 296 .Fa nt .
 297 The callback is invoked with the user-supplied value
 298 .Fa arg
 299 and a pointer to the current node.
 300 .\"
 301 .Sh RETURN VALUES
 302 The function
 303 .Fn ieee80211_next_scan
 304 returns 0,
 305 if a full cycle of scanning on all available radio channels is done.
 306 Otherwise, 1 is returned.
 307 .Pp
 308 .\"
 309 The function
 310 .Fn ieee80211_find_txnode
 311 returns a node entry that is suitable to be used to send a frame to
 312 .Fa macaddr .
 313 If there is no suitable node found,
 314 .Dv NULL
 315 is returned.
 316 .Pp
 317 .\"
 318 The function
 319 .Fn ieee80211_find_rxnode
 320 returns a node entry that represents the sender of
 321 .Fa wh .
 322 If no suitable node entry can be found,
 323 .Va ic_bss
 324 is returned.
 325 .Pp
 326 .\"
 327 The function
 328 .Fn ieee80211_find_node
 329 returns a pointer to the node entry which matches
 330 .Fa macaddr .
 331 If no match is found,
 332 .Dv NULL
 333 is returned.
 334 .\"
 335 .Sh SEE ALSO
 336 .Xr ieee80211 9 ,
 337 .Xr ifnet 9
 338 .Sh HISTORY
 339 The
 340 .Nm ieee80211
 341 series of functions first appeared in
 342 .Nx 1.5 ,
 343 and were later ported to
 344 .Fx 4.6 .
 345 .Sh AUTHORS
 346 .An -nosplit
 347 This man page was written by
 348 .An Bruce M. Simpson Aq bms@FreeBSD.org
 349 and
 350 .An Darron Broad Aq darron@kewl.org .