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