1.\" $OpenBSD: ieee80211.9,v 1.15 2022/03/29 18:15:52 naddy Exp $ 2.\" 3.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> 4.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD: src/share/man/man9/ieee80211.9,v 1.3 2004/07/07 12:59:39 ru Exp $ 29.\" $Id: ieee80211.9,v 1.15 2022/03/29 18:15:52 naddy Exp $ 30.\" 31.Dd $Mdocdate: March 29 2022 $ 32.Dt IEEE80211_IFATTACH 9 33.Os 34.Sh NAME 35.Nm ieee80211_ifattach , ieee80211_ifdetach , 36.Nm ieee80211_mhz2ieee , ieee80211_chan2ieee , ieee80211_ieee2mhz , 37.Nm ieee80211_media_init , ieee80211_media_change , ieee80211_media_status , 38.Nm ieee80211_watchdog , 39.Nm ieee80211_setmode , ieee80211_chan2mode , 40.Nm ieee80211_rate2media , ieee80211_media2rate , 41.Nm ieee80211_rate2plcp , ieee80211_plcp2rate 42.Nd core 802.11 network stack functions 43.Sh SYNOPSIS 44.In net80211/ieee80211_var.h 45.In net80211/ieee80211_proto.h 46.Ft void 47.Fn ieee80211_ifattach "struct ifnet *ifp" 48.Ft void 49.Fn ieee80211_ifdetach "struct ifnet *ifp" 50.Ft u_int 51.Fn ieee80211_mhz2ieee "u_int freq" "u_int flags" 52.Ft u_int 53.Fn ieee80211_chan2ieee "struct ieee80211com *ic" \ 54"const struct ieee80211_channel *c" 55.Ft u_int 56.Fn ieee80211_ieee2mhz "u_int chan" "u_int flags" 57.Ft void 58.Fo ieee80211_media_init 59.Fa "struct ifnet *ifp" "ifm_change_cb_t media_change" 60.Fa "ifm_stat_cb_t media_stat" 61.Fc 62.Ft int 63.Fn ieee80211_media_change "struct ifnet *ifp" 64.Ft void 65.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr" 66.Ft void 67.Fn ieee80211_watchdog "struct ifnet *ifp" 68.Ft int 69.Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode" 70.Ft enum ieee80211_phymode 71.Fo ieee80211_chan2mode 72.Fa "struct ieee80211com *ic" "const struct ieee80211_channel *chan" 73.Fc 74.Ft int 75.Fo ieee80211_rate2media 76.Fa "struct ieee80211com *ic" "int rate" "enum ieee80211_phymode mode" 77.Fc 78.Ft int 79.Fn ieee80211_media2rate "int mword" 80.Ft u_int8_t 81.Fn ieee80211_rate2plcp "u_int8_t rate" "enum ieee80211_phymode mode" 82.Ft u_int8_t 83.Fn ieee80211_plcp2rate "u_int8_t plcp" "enum ieee80211_phymode mode" 84.Sh DESCRIPTION 85The 86.Nm ieee80211 87collection of functions are used to manage wireless network interfaces in the 88system which use the system's software 802.11 network stack. 89Most of these functions require that attachment to the stack is performed 90before calling. 91Several utility functions are also provided; these are safe to call from 92any driver without prior initialization. 93.Pp 94.\" 95The 96.Fn ieee80211_ifattach 97function attaches the network interface 98.Fa ifp 99to the 802.11 network stack layer. 100This function must be called before using any of the 101.Nm ieee80211 102functions which need to store driver state across invocations. 103The 104.Vt struct ifnet 105instance pointed to by 106.Fa ifp 107MUST be an instance of 108.Vt struct ieee80211com , 109with various fields initialized to tell 110.Nm ieee80211 111about its capabilities. 112This function performs Ethernet and BPF attachment (by calling 113.Fn ether_ifattach 114and 115.Fn bpfattach ) 116on behalf of the caller. 117It also implements the 118.Vt ifmedia 119interface. 120.Pp 121.\" 122The 123.Fn ieee80211_ifdetach 124function frees any 125.Nm ieee80211 126structures associated with the driver, and performs Ethernet and BPF 127detachment on behalf of the caller. 128.Pp 129.\" 130The 131.Fn ieee80211_mhz2ieee 132utility function converts the frequency 133.Fa freq 134(specified in MHz) to an IEEE 802.11 channel number. 135The 136.Fa flags 137argument is a hint which specifies whether the frequency is in 138the 2GHz ISM band 139.Pq Vt IEEE80211_CHAN_2GHZ 140or the 5GHz band 141.Pq Vt IEEE80211_CHAN_5GHZ ; 142appropriate clipping of the result is then performed. 143.Pp 144.\" 145The 146.Fn ieee80211_chan2ieee 147function converts the channel specified in 148.Fa *c 149to an IEEE channel number for the driver 150.Fa ic . 151If the conversion would be invalid, an error message is printed to the 152system console. 153This function requires that the driver is hooked up to the 154.Nm ieee80211 155subsystem. 156.Pp 157.\" 158The 159.Fn ieee80211_ieee2mhz 160utility function converts the IEEE channel number 161.Ft chan 162to a frequency (in MHz). 163The 164.Fa flags 165argument is a hint which specifies whether the frequency is in 166the 2GHz ISM band 167.Pq Vt IEEE80211_CHAN_2GHZ 168or the 5GHz band 169.Pq Vt IEEE80211_CHAN_5GHZ ; 170appropriate clipping of the result is then performed. 171.Pp 172.\" 173The 174.Fn ieee80211_media_init 175function initializes media data structures used by the 176.Vt ifmedia 177interface, for the driver 178.Fa ifp . 179It must be called by the driver after calling 180.Fn ieee80211_ifattach 181and before calling most 182.Nm ieee80211 183functions. 184The 185.Fa media_change 186and 187.Fa media_stat 188arguments specify helper functions which will be invoked by the 189.Vt ifmedia 190framework when the user changes or queries media options, 191using a command such as 192.Xr ifconfig 8 . 193.Pp 194.\" 195The 196.Fn ieee80211_media_status 197and 198.Fn ieee80211_media_change 199functions are device-independent handlers for 200.Vt ifmedia 201commands and are not intended to be called directly. 202.Pp 203.\" 204The 205.Fn ieee80211_watchdog 206function is intended to be called from a driver's 207.Va if_watchdog 208routine. 209It is used to perform periodic cleanup of state within the software 802.11 210stack, as well as timing out scans. 211.Pp 212.\" 213The 214.Fn ieee80211_setmode 215function is called from within the 802.11 stack to change the mode 216of the driver's PHY; it is not intended to be called directly. 217.Pp 218.\" 219The 220.Fn ieee80211_chan2mode 221function returns the PHY mode required for use with the channel 222.Fa chan 223on the device 224.Fa ic . 225This is typically used when selecting a rate set, to be advertised in 226beacons, for example. 227.Pp 228.\" 229The 230.Fn ieee80211_rate2media 231function converts the bit rate 232.Fa rate 233(measured in units of 0.5Mbps) to an 234.Vt ifmedia 235sub-type, for the device 236.Fa ic 237running in PHY mode 238.Fa mode . 239The 240.Fn ieee80211_media2rate 241function performs the reverse of this conversion, 242returning the bit rate (in 0.5Mbps units) corresponding to an 243.Vt ifmedia 244sub-type. 245.Pp 246.\" 247The 248.Fn ieee80211_rate2plcp 249function converts the bit rate 250.Fa rate 251(measured in units of 0.5Mbps) to a 252.Vt plcp 253signal (in msb-first R4-R1 format). 254The 255.Fn ieee80211_plcp2rate 256function performs the reverse of this conversion, 257returning the bit rate (in 0.5Mbps units) corresponding to a 258.Vt plcp 259signal (in msb-first R4-R1 format). 260.\" 261.Sh SEE ALSO 262.Xr ifmedia 4 , 263.Xr ieee80211_crypto 9 , 264.Xr ieee80211_input 9 , 265.Xr ieee80211_ioctl 9 , 266.Xr ieee80211_node 9 , 267.Xr ieee80211_output 9 , 268.Xr ieee80211_proto 9 , 269.Xr ieee80211_radiotap 9 , 270.Xr rssadapt 9 271.Sh HISTORY 272The 273.Nm ieee80211 274series of functions first appeared in 275.Nx 1.5 , 276and were later ported to 277.Fx 4.6 278and 279.Ox 3.6 . 280.Sh AUTHORS 281.An -nosplit 282This man page was written by 283.An Bruce M. Simpson Aq Mt bms@FreeBSD.org 284and 285.An Darron Broad Aq Mt darron@kewl.org . 286