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