| ieee80211_node.9 (571dba6ec9f25ecf7582dc2192daf1ceea70065f) | ieee80211_node.9 (692eebe092e81927e190dd5eeb4f65d2324ea3fa) |
|---|---|
| 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: --- 11 unchanged lines hidden (view full) --- 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$ | 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: --- 11 unchanged lines hidden (view full) --- 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.\" | 28.\" |
| 30.Dd July 4, 2004 | 29.Dd August 4, 2009 |
| 31.Dt IEEE80211_NODE 9 32.Os 33.Sh NAME | 30.Dt IEEE80211_NODE 9 31.Os 32.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 | 33.Nm ieee80211_node |
| 49.Nd software 802.11 stack node management functions 50.Sh SYNOPSIS 51.In net80211/ieee80211_var.h | 34.Nd software 802.11 stack node management functions 35.Sh SYNOPSIS 36.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" | 37.\" 38.Ft struct ieee80211_node * 39.Fo ieee80211_find_rxnode 40.Fa "struct ieee80211com *" 41.Fa "const struct ieee80211_frame_min *" |
| 67.Fc | 42.Fc |
| 68.Ft void 69.Fn ieee80211_end_scan "struct ifnet *ifp" | 43.\" |
| 70.Ft struct ieee80211_node * | 44.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" | 45.Fo ieee80211_find_rxnode_withkey 46.Fa "struct ieee80211com *" 47.Fa "const struct ieee80211_frame_min *" 48.Fa "ieee80211_keyix" |
| 80.Fc | 49.Fc |
| 50.\" 51.Ft struct ieee80211_node * 52.Fn ieee80211_ref_node "struct ieee80211_node *" 53.\" |
|
| 81.Ft void | 54.Ft void |
| 82.Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni" | 55.Fn ieee80211_unref_node "struct ieee80211_node *" 56.\" |
| 83.Ft void | 57.Ft void |
| 84.Fn ieee80211_free_allnodes "struct ieee80211com *ic" | 58.Fn ieee80211_free_node "struct ieee80211_node *" 59.\" |
| 85.Ft void | 60.Ft void |
| 86.Fn ieee80211_timeout_nodes "struct ieee80211com *ic" 87.Ft void | |
| 88.Fo ieee80211_iterate_nodes | 61.Fo ieee80211_iterate_nodes |
| 89.Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg" | 62.Fa "struct ieee80211_node_table *" 63.Fa "ieee80211_iter_func *f" 64.Fa "void *arg" |
| 90.Fc | 65.Fc |
| 91.Sh DESCRIPTION 92These functions are used to manage node lists within the software 93802.11 stack. 94These lists are typically used for implementing host-mode AP functionality, 95or providing signal quality information about neighbouring nodes. 96.Pp | |
| 97.\" | 66.\" |
| 98The 99.Fn ieee80211_node_attach 100function is called from 101.Xr ieee80211_ifattach 9 102to initialize node database management callbacks for the interface 103.Fa ifp 104(specifically for memory allocation, node copying and node 105signal inspection). 106These functions may be overridden in special circumstances, 107as long as this is done after calling 108.Xr ieee80211_ifattach 9 109and prior to any other call which may allocate a node. 110.Pp | 67.Ft void 68.Fo ieee80211_dump_nodes 69.Fa "struct ieee80211_node_table *" 70.Fc |
| 111.\" | 71.\" |
| 72.Ft void 73.Fo ieee80211_dump_node 74.Fa "struct ieee80211_node *" 75.Fc 76.Sh DESCRIPTION |
|
| 112The | 77The |
| 113.Fn ieee80211_node_lateattach 114function initialises the 115.Va ic_bss 116node element of the interface 117.Fa ifp 118during 119.Xr ieee80211_media_init 9 . 120This late attachment is to account for certain special cases described under 121.Fn ieee80211_node_attach . | 78.Nm net80211 79layer that supports 802.11 device drivers maintains a database of 80peer stations called the 81.Dq node table 82in the 83.Vt ic_sta 84entry of the 85.Vt ieee80211com 86structure. 87Station mode vaps create an entry for the access point 88the station is associated to. 89AP mode vaps create entries for associated stations. 90Adhoc and mesh mode vaps create entries for neighbor stations. 91WDS mode vaps create an entry for the peer station. 92Stations for all vaps reside in the same table; each node 93entry has a 94.Vt ni_vap 95field that identifies the vap that created it. 96In some instances an entry is used by multiple vaps (e.g. for 97dynamic WDS a station associated to an ap vap may also be the peer 98of a WDS vap). |
| 122.Pp | 99.Pp |
| 123.\" | 100Node table entries are reference counted. 101That is, there is a count of all long term references that determines 102when an entry may be reclaimed. 103References are held by every in-flight frame sent to a station to 104insure the entry is not reclaimed while the frame is queued or otherwise 105held by a driver. 106Routines that lookup a table entry return a 107.Dq held reference 108(i.e. a pointer to a table entry with the reference count incremented). |
| 124The | 109The |
| 125.Fn ieee80211_node_detach 126function destroys all node database state associated with the interface 127.Fa ifp , 128and is usually called during device detach. | 110.Fn ieee80211_ref_node 111and 112.Fn ieee80211_unref_node 113calls explicitly increment/decrement the reference count of a node, 114but are rarely used. 115Instead most callers use 116.Fn ieee80211_free_node 117to release a reference and, if the count goes to zero, reclaim the 118table entry. |
| 129.Pp | 119.Pp |
| 130.\" 131The 132.Fn ieee80211_begin_scan 133function initialises the node database in preparation of an active 134scan for an access point on the interface 135.Fa ifp . 136The scan begins on the next radio channel by calling 137.Fn ieee80211_next_scan 138internally. 139The actual scanning for an access point is not automated; 140the device driver itself only handles setting the radio frequency 141of the card and stepping through the channels. | 120The station table and its entries are exposed to drivers in several ways. 121Each frame transmitted to a station includes a reference to the 122associated node in the 123.Vt m_pkthdr.rcvif 124field. 125This reference must be reclaimed by the driver when transmit processing 126is done. 127For each frame received the driver must lookup the table entry to 128use in dispatching the frame 129.Dq up the stack . 130This lookup implicitly obtains a reference to the table entry and 131the driver must reclaim the reference when frame processing is completed. 132Otherwise drivers frequently inspect the contents of the 133.Vt iv_bss 134node when handling state machine changes as important information 135is maintained in the data structure. |
| 142.Pp | 136.Pp |
| 143.\" 144The 145.Fn ieee80211_next_scan 146function is used to inform the 147.Xr ieee80211 9 148layer that the interface 149.Fa ifp 150is now scanning for an access point on the next radio channel. 151A device driver is expected to first call 152.Fn ieee80211_begin_scan , 153to initialize the node database, 154then set the radio channel on the device; 155then, after a certain time has elapsed (200ms for example), call 156.Fn ieee80211_next_scan 157to move to the next channel. 158Typically, a callout is used to automate this process; see 159.Xr callout_init 9 160for more information on how to use callouts. | 137The node table is opaque to drivers. 138Entries may be looked up using one of the pre-defined API's or the 139.Fn ieee80211_iterate_nodes 140call may be used to iterate through all entries to do per-node 141processing or implement some non-standard search mechanism. 142Note that 143.Fn ieee80211_iterate_nodes 144is single-threaded per-device 145and the effort processing involved is fairly 146substantial so it should be used carefully. |
| 161.Pp | 147.Pp |
| 162.\" 163The 164.Fn ieee80211_create_ibss 165function sets up the net80211-specific portion of an interface's softc, 166.Fa ic , 167for use in IBSS mode. | 148Two routines are provided to print the contents of nodes to the console 149for debugging: 150.Fn ieee80211_dump_node 151displays the contents of a single node while 152.Fn ieee80211_dump_nodes 153displays the contents of the specified node table. 154Nodes may also be displayed using 155.Xr ddb 9 156with the 157.Dq show node 158directive and the station node table can be displayed with 159.Dq show statab . 160.Sh DRIVER PRIVATE STATE 161Node data structures may be extended by the driver to include 162driver-private state. 163This is done by overriding the 164.Vt ic_node_alloc 165method used to allocate a node table entry. 166The driver method must allocate a structure that is an extension 167of the 168.Vt ieee80211_node 169structure. 170For example the 171.Xr iwi 4 172driver defines a private node structure as: 173.Bd -literal -offset indent 174struct iwi_node { 175 struct ieee80211_node in_node; 176 int in_station; 177}; 178.Ed |
| 168.Pp | 179.Pp |
| 169.\" 170The 171.Fn ieee80211_end_scan 172function is called by 173.Fn ieee80211_next_scan 174when the state machine has peformed a full cycle of scanning on 175all available radio channels. 176Internally, 177.Fn ieee80211_end_scan 178will inspect the node cache associated with the interface 179.Fa ifp 180for suitable access points found during scanning, and associate with one, 181should the parameters of the node match those of the configuration 182requested from userland. | 180and then provides a private allocation routine that does this: 181.Bd -literal -offset indent 182static struct ieee80211_node * 183iwi_node_alloc(struct ieee80211vap *vap, 184 const uint8_t mac[IEEE80211_ADDR_LEN]) 185{ 186 struct iwi_node *in; 187 188 in = malloc(sizeof (struct iwi_node), M_80211_NODE, 189 M_NOWAIT | M_ZERO); 190 if (in == NULL) 191 return NULL; 192 in->in_station = -1; 193 return &in->in_node; 194} 195.Ed |
| 183.Pp | 196.Pp |
| 184.\" 185The 186.Fn ieee80211_alloc_node 187function allocates an instance of 188.Vt "struct ieee80211_node" 189for a node having the MAC address 190.Fa macaddr , 191and associates it with the interface 192.Fa ic . 193If the allocation is successful, the node structure is initialised by 194.Fn ieee80211_setup_node ; 195otherwise, 196.Dv NULL 197is returned. | 197Note that when reclaiming a node allocated by the driver the 198.Dq parent method 199must be called to ensure 200.Nm net80211 201state is reclaimed; for example: 202.Bd -literal -offset indent 203static void 204iwi_node_free(struct ieee80211_node *ni) 205{ 206 struct ieee80211com *ic = ni->ni_ic; 207 struct iwi_softc *sc = ic->ic_ifp->if_softc; 208 struct iwi_node *in = (struct iwi_node *)ni; 209 210 if (in->in_station != -1) 211 free_unr(sc->sc_unr, in->in_station); 212 sc->sc_node_free(ni); /* invoke net80211 free handler */ 213} 214.Ed |
| 198.Pp | 215.Pp |
| 199.\" 200The 201.Fn ieee80211_dup_bss 202function is similar to 203.Fn ieee80211_alloc_node , 204but is instead used to create a node database entry for the BSSID 205.Fa macaddr 206associated with the interface 207.Fa ic . 208If the allocation is successful, the node structure is initialised by 209.Fn ieee80211_setup_node ; 210otherwise, 211.Dv NULL 212is returned. 213.Pp 214.\" 215The 216.Fn ieee80211_find_node 217function will iterate through the node list associated with the interface 218.Fa ic , 219searching for a node entry which matches 220.Fa macaddr . 221If the entry is found, its reference count is incremented, and 222a pointer to the node is returned; otherwise, 223.Dv NULL 224will be returned. 225.Pp 226.\" 227The 228.Fn ieee80211_lookup_node 229function is similar to 230.Fn ieee80211_find_node , 231with an additional argument 232.Fa chan 233which is used to specify a channel for the match. 234If the entry is found, its reference count is incremented, and 235a pointer to the node is returned; otherwise, 236.Dv NULL 237will be returned. 238.Pp 239.\" 240The 241.Fn ieee80211_free_node 242function will remove the node 243.Fa ni 244from the node database entries associated with the interface 245.Fa ic , 246and free any memory associated with the node. 247This private method can be overridden in 248.Fn ieee80211_node_attach . 249.\" 250.Pp 251The 252.Fn ieee80211_free_allnodes 253function will iterate through the node list calling 254.Fn ieee80211_free_node 255for all nodes associated with the interface 256.Fa ic . 257.Pp 258.\" 259The 260.Fn ieee80211_timeout_nodes 261checks if the inactivity timer of each node associated with the interface 262.Fa ic 263has exceeded the pre-defined constant 264.Dv IEEE80211_INACT_MAX . 265If so, then the node is freed, after sending a deauthentication message. 266.Pp 267.\" 268The 269.Fn ieee80211_iterate_nodes 270function will call the user-defined callback function 271.Fa f 272for all nodes in the node database associated with the interface 273.Fa ic . 274The callback is invoked with the with the user-supplied value 275.Fa arg 276and a pointer to the current node. 277.\" | 216Beware that care must be taken to avoid holding references that 217might cause nodes from being reclaimed. 218.Nm net80211 219will reclaim a node when the last reference is reclaimed in 220its data structures. 221However if a driver holds additional references then 222.Nm net80211 223will not recognize this and table entries will not be reclaimed. 224Such references should not be needed if the driver overrides the 225.Vt ic_node_cleanup 226and/or 227.Vt ic_node_free 228methods. 229.Sh KEY TABLE SUPPORT 230Node table lookups are typically done using a hash of the stations' 231mac address. 232When receiving frames this is sufficient to find the node table entry 233for the transmitter. 234But some devices also identify the sending station in the device 235state received with each frame and this data can be used to optimize 236lookups on receive using a companion table called the 237.Dq keytab . 238This table records a separate node table reference that can be fetched 239without any locking using the table index. 240This logic is handled with the 241.Fn ieee80211_find_rxnode_withkey 242call: if a keytab entry is found using the specified index then it is 243returned directly; otherwise a normal lookup is done and the keytab 244entry is written using the specified index. 245If the specified index is 246.Dv IEEE80211_KEYIX_NONE 247then a normal lookup is done without a table update. |
| 278.Sh SEE ALSO | 248.Sh SEE ALSO |
| 249.Xr ddb 9 |
|
| 279.Xr ieee80211 9 , | 250.Xr ieee80211 9 , |
| 280.Xr ifnet 9 281.Sh HISTORY 282The 283.Nm ieee80211 284series of functions first appeared in 285.Nx 1.5 , 286and were later ported to 287.Fx 4.6 . 288.Sh AUTHORS 289.An -nosplit 290This manual page was written by 291.An Bruce M. Simpson Aq bms@FreeBSD.org 292and 293.An Darron Broad Aq darron@kewl.org . | 251.Xr ieee80211_proto 9 , |