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