| blob | b7656c3e3ca78111ab261954e0d4b259dcc25c41 |
1 .\" $NetBSD: ieee80211.9,v 1.3 2006/09/12 11:05:23 pooka Exp $
2 .\"
3 .\"
4 .\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
5 .\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 .\" SUCH DAMAGE.
28 .\"
29 .\" $FreeBSD: src/share/man/man9/ieee80211.9,v 1.3 2004/07/07 12:59:39 ru Exp $
30 .\"
31 .Dd September 12, 2006
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 ieee80211com *ic"
47 .Ft void
48 .Fn ieee80211_ifdetach "struct ieee80211com *ic"
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 ieee80211com *ic" "ifm_change_cb_t media_change"
58 .Fa "ifm_stat_cb_t media_stat"
59 .Fc
60 .Ft int
61 .Fn ieee80211_media_change "struct ifnet *ifp"
62 .Ft void
63 .Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr"
64 .Ft void
65 .Fn ieee80211_watchdog "struct ieee80211com *ic"
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 wireless network interface
92 .Fa ic
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 This function also performs Ethernet and BPF attachment (by calling
98 .Fn ether_ifattach
99 and
100 .Fn bpfattach2 )
101 on behalf of the caller.
102 .Pp
103 .\"
104 The
105 .Fn ieee80211_ifdetach
106 function frees any
107 .Nm ieee80211
108 structures associated with the driver, and performs Ethernet and BPF
109 detachment on behalf of the caller.
110 .Pp
111 .\"
112 The
113 .Fn ieee80211_mhz2ieee
114 utility function converts the frequency
115 .Fa freq
116 (specified in MHz) to an IEEE 802.11 channel number.
117 The
118 .Fa flags
119 argument is a hint which specifies whether the frequency is in
120 the 2GHz ISM band
121 .Pq Vt IEEE80211_CHAN_2GHZ
122 or the 5GHz band
123 .Pq Vt IEEE80211_CHAN_5GHZ ;
124 appropriate clipping of the result is then performed.
125 .Pp
126 .\"
127 The
128 .Fn ieee80211_chan2ieee
129 function converts the channel specified in
130 .Fa *c
131 to an IEEE channel number for the driver
132 .Fa ic .
133 If the conversion would be invalid, an error message is printed to the
134 system console.
135 This function REQUIRES that the driver is hooked up to the
136 .Nm ieee80211
137 subsystem.
138 .Pp
139 .\"
140 The
141 .Fn ieee80211_ieee2mhz
142 utility function converts the IEEE channel number
143 .Ft chan
144 to a frequency (in MHz).
145 The
146 .Fa flags
147 argument is a hint which specifies whether the frequency is in
148 the 2GHz ISM band
149 .Pq Vt IEEE80211_CHAN_2GHZ
150 or the 5GHz band
151 .Pq Vt IEEE80211_CHAN_5GHZ ;
152 appropriate clipping of the result is then performed.
153 .Pp
154 .\"
155 The
156 .Fn ieee80211_media_init
157 function initializes media data structures used by the
158 .Vt ifmedia
159 interface for the driver
160 .Fa ic .
161 It must be called by the driver after calling
162 .Fn ieee80211_ifattach
163 and before calling most
164 .Nm ieee80211
165 functions.
166 The
167 .Fa media_change
168 and
169 .Fa media_stat
170 arguments specify helper functions which will be invoked by the
171 .Vt ifmedia
172 framework when the user changes or queries media options,
173 using a command such as
174 .Xr ifconfig 8 .
175 .Pp
176 .\"
177 The
178 .Fn ieee80211_media_status
179 and
180 .Fn ieee80211_media_change
181 functions are device-independent handlers for
182 .Vt ifmedia
183 commands and are not intended to be called directly.
184 .Pp
185 .\"
186 The
187 .Fn ieee80211_watchdog
188 function is intended to be called from a driver's
189 .Va if_watchdog
190 routine.
191 It is used to perform periodic cleanup of state within the software 802.11
192 stack, as well as timing out scans.
193 .Pp
194 .\"
195 The
196 .Fn ieee80211_setmode
197 function is called from within the 802.11 stack to change the mode
198 of the driver's PHY; it is not intended to be called directly.
199 .Pp
200 .\"
201 The
202 .Fn ieee80211_chan2mode
203 function returns the PHY mode required for use with the channel
204 .Fa chan
205 on the device
206 .Fa ic .
207 This is typically used when selecting a rate set, to be advertised in
208 beacons, for example.
209 .Pp
210 .\"
211 The
212 .Fn ieee80211_rate2media
213 function converts the bit rate
214 .Fa rate
215 (measured in units of 0.5Mbps) to an
216 .Vt ifmedia
217 sub-type, for the device
218 .Fa ic
219 running in PHY mode
220 .Fa mode .
221 The
222 .Fn ieee80211_media2rate
223 performs the reverse of this conversion, returning the bit rate (in 0.5Mbps
224 units) corresponding to an
225 .Vt ifmedia
226 sub-type.
227 .\"
228 .Sh SEE ALSO
229 .Xr ieee80211_crypto 9 ,
230 .Xr ieee80211_input 9 ,
231 .Xr ieee80211_ioctl 9 ,
232 .Xr ieee80211_node 9 ,
233 .Xr ieee80211_output 9 ,
234 .Xr ieee80211_proto 9 ,
235 .Xr ieee80211_radiotap 9
236 .Sh HISTORY
237 The
238 .Nm ieee80211
239 series of functions first appeared in
240 .Nx 1.5 ,
241 and were later ported to
242 .Fx 4.6 .
243 .Sh AUTHORS
244 .An -nosplit
245 This man page was written by
246 .An Bruce M. Simpson Aq bms@FreeBSD.org
247 and
248 .An Darron Broad Aq darron@kewl.org .