Add the ieee80211(9) API manual pages.
[dragonfly.git] / share / man / man9 / ieee80211.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.9,v 1.1 2004/07/27 14:50:56 hmp Exp $
29 .\" $Id: ieee80211.9,v 1.3 2004/07/07 12:59:39 ru Exp $
30 .\"
31 .Dd March 2, 2004
32 .Dt IEEE80211 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 .Nd core 802.11 network stack functions
42 .Sh SYNOPSIS
43 .In net80211/ieee80211_var.h
44 .In net80211/ieee80211_proto.h
45 .Ft void
46 .Fn ieee80211_ifattach "struct ifnet *ifp"
47 .Ft void
48 .Fn ieee80211_ifdetach "struct ifnet *ifp"
49 .Ft u_int
50 .Fn ieee80211_mhz2ieee "u_int freq" "u_int flags"
51 .Ft u_int
52 .Fn ieee80211_chan2ieee "struct ieee80211com *ic" "struct ieee80211_channel *c"
53 .Ft u_int
54 .Fn ieee80211_ieee2mhz "u_int chan" "u_int flags"
55 .Ft void
56 .Fo ieee80211_media_init
57 .Fa "struct ifnet *ifp" "ifm_change_cb_t media_change"
58 .Fa "ifm_stat_cb_t media_stat"
59 .Fc
60 .Fa int
61 .Fn ieee80211_media_change "struct ifnet *ifp"
62 .Fa void
63 .Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr"
64 .Ft void
65 .Fn ieee80211_watchdog "struct ifnet *ifp"
66 .Ft int
67 .Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode"
68 .Ft enum ieee80211_phymode
69 .Fo ieee80211_chan2mode
70 .Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
71 .Fc
72 .Ft int
73 .Fo ieee80211_rate2media
74 .Fa "struct ieee80211com *ic" "int rate" "enum ieee80211_phymode mode"
75 .Fc
76 .Ft int
77 .Fn ieee80211_media2rate "int mword"
78 .Sh DESCRIPTION
79 The
80 .Nm ieee80211
81 collection of functions are used to manage wireless network interfaces in the
82 system which use the system's software 802.11 network stack.
83 Most of these functions require that attachment to the stack is performed
84 before calling.
85 Several utility functions are also provided; these are safe to call from
86 any driver without prior initialization.
87 .Pp
88 .\"
89 The
90 .Fn ieee80211_ifattach
91 function attaches the network interface
92 .Fa ifp
93 to the 802.11 network stack layer.
94 This function must be called before using any of the
95 .Nm ieee80211
96 functions which need to store driver state across invocations;
97 The
98 .Vt struct ifnet
99 instance pointed to by
100 .Fa ifp
101 MUST be an instance of
102 .Vt struct ieee80211com ,
103 with various fields initialized to tell
104 .Nm ieee80211
105 about its capabilities.
106 This function performs Ethernet and BPF attachment (by calling
107 .Fn ether_ifattach
108 and
109 .Fn bpfattach2 )
110 on behalf of the caller.
111 It also implements the
112 .Vt ifmedia
113 interface.
114 .Pp
115 .\"
116 The
117 .Fn ieee80211_ifdetach
118 function frees any
119 .Nm ieee80211
120 structures associated with the driver, and performs Ethernet and BPF
121 detachment on behalf of the caller.
122 .Pp
123 .\"
124 The
125 .Fn ieee80211_mhz2ieee
126 utility function converts the frequency
127 .Fa freq
128 (specified in MHz) to an IEEE 802.11 channel number.
129 The
130 .Fa flags
131 argument is a hint which specifies whether the frequency is in
132 the 2GHz ISM band
133 .Pq Vt IEEE80211_CHAN_2GHZ
134 or the 5GHz band
135 .Pq Vt IEEE80211_CHAN_5GHZ ;
136 appropriate clipping of the result is then performed.
137 .Pp
138 .\"
139 The
140 .Fn ieee80211_chan2ieee
141 function converts the channel specified in
142 .Fa *c
143 to an IEEE channel number for the driver
144 .Fa ic .
145 If the conversion would be invalid, an error message is printed to the
146 system console.
147 This function REQUIRES that the driver is hooked up to the
148 .Nm ieee80211
149 subsystem.
150 .Pp
151 .\"
152 The
153 .Fn ieee80211_ieee2mhz
154 utility function converts the IEEE channel number
155 .Ft chan
156 to a frequency (in MHz).
157 The
158 .Fa flags
159 argument is a hint which specifies whether the frequency is in
160 the 2GHz ISM band
161 .Pq Vt IEEE80211_CHAN_2GHZ
162 or the 5GHz band
163 .Pq Vt IEEE80211_CHAN_5GHZ ;
164 appropriate clipping of the result is then performed.
165 .Pp
166 .\"
167 The
168 .Fn ieee80211_media_init
169 function initializes media data structures used by the
170 .Vt ifmedia
171 interface, for the driver
172 .Fa ifp .
173 It must be called by the driver after calling
174 .Fn ieee80211_attach
175 and before calling most
176 .Nm ieee80211
177 functions.
178 The
179 .Fa media_change
180 and
181 .Fa media_stat
182 arguments specify helper functions which will be invoked by the
183 .Vt ifmedia
184 framework when the user changes or queries media options,
185 using a command such as
186 .Xr ifconfig 8 .
187 .Pp
188 .\"
189 The
190 .Fn ieee80211_media_status
191 and
192 .Fn ieee80211_media_change
193 functions are device-independent handlers for
194 .Vt ifmedia
195 commands and are not intended to be called directly.
196 .Pp
197 .\"
198 The
199 .Fn ieee80211_watchdog
200 function is intended to be called from a driver's
201 .Va if_watchdog
202 routine.
203 It is used to perform periodic cleanup of state within the software 802.11
204 stack, as well as timing out scans.
205 .Pp
206 .\"
207 The
208 .Fn ieee80211_setmode
209 function is called from within the 802.11 stack to change the mode
210 of the driver's PHY; it is not intended to be called directly.
211 .Pp
212 .\"
213 The
214 .Fn ieee80211_chan2mode
215 function returns the PHY mode required for use with the channel
216 .Fa chan
217 on the device
218 .Fa ic .
219 This is typically used when selecting a rate set, to be advertised in
220 beacons, for example.
221 .Pp
222 .\"
223 The
224 .Fn ieee80211_rate2media
225 function converts the bit rate
226 .Fa rate
227 (measured in units of 0.5Mbps) to an
228 .Vt ifmedia
229 sub-type, for the device
230 .Fa ic
231 running in PHY mode
232 .Fa mode .
233 The
234 .Fn ieee80211_media2rate
235 performs the reverse of this conversion, returning the bit rate (in 0.5Mbps
236 units) corresponding to an
237 .Vt ifmedia
238 sub-type.
239 .\"
240 .Sh SEE ALSO
241 .Xr ieee80211_crypto 9 ,
242 .Xr ieee80211_input 9 ,
243 .Xr ieee80211_ioctl 9 ,
244 .Xr ieee80211_node 9 ,
245 .Xr ieee80211_output 9 ,
246 .Xr ieee80211_proto 9 ,
247 .Xr ieee80211_radiotap 9 ,
248 .Xr ifnet 9
249 .Sh HISTORY
250 The
251 .Nm ieee80211
252 series of functions first appeared in
253 .Nx 1.5 ,
254 and were later ported to
255 .Fx 4.6 .
256 .Sh AUTHORS
257 .An -nosplit
258 This man page was written by
259 .An Bruce M. Simpson Aq bms@FreeBSD.org
260 and
261 .An Darron Broad Aq darron@kewl.org .