ieee80211_{amrr,vap}.9: Fix typos in .Dt
[dragonfly.git] / share / man / man9 / ieee80211_vap.9
1 .\"
2 .\" Copyright (c) 2009 Sam Leffler, Errno Consulting
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 .\" SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD: src/share/man/man9/ieee80211_vap.9,v 1.2 2009/09/18 00:33:47 brueffer Exp $
27 .\"
28 .Dd April 28, 2010
29 .Dt IEEE80211_VAP 9
30 .Os
31 .Sh NAME
32 .Nm net80211_vap
33 .Nd 802.11 network layer virtual radio support
34 .Sh SYNOPSIS
35 .In net80211/ieee80211_var.h
36 .Ft int
37 .Fo ieee80211_vap_setup
38 .Fa "struct ieee80211com *"
39 .Fa "struct ieee80211vap *"
40 .Fa "const char name[IFNAMSIZ]"
41 .Fa "int unit"
42 .Fa "int opmode"
43 .Fa "int flags"
44 .Fa "const uint8_t bssid[IEEE80211_ADDR_LEN]"
45 .Fa "const uint8_t macaddr[IEEE80211_ADDR_LEN]"
46 .Fc
47 .\"
48 .Ft int
49 .Fo ieee80211_vap_attach
50 .Fa "struct ieee80211vap *"
51 .Fa "ifm_change_cb_t media_change"
52 .Fa "ifm_stat_cb_t media_stat"
53 .Fc
54 .\"
55 .Ft void
56 .Fn ieee80211_vap_detach "struct ieee80211vap *"
57 .Sh DESCRIPTION
58 The
59 .Nm net80211
60 software layer provides a support framework for drivers that includes
61 a virtual radio API that is exported to
62 users through network interfaces (aka vaps) that are cloned from the
63 underlying device.
64 These interfaces have an operating mode
65 (station, adhoc, hostap, wds, monitor, etc.)
66 that is fixed for the lifetime of the interface.
67 Devices that can support multiple concurrent interfaces allow
68 multiple vaps to be cloned.
69 .Pp
70 The virtual radio interface defined by the
71 .Nm net80211
72 layer means that drivers must be structured to follow specific rules.
73 Drivers that support only a single interface at any time must still
74 follow these rules.
75 .Pp
76 The virtual radio architecture splits state between a single per-device
77 .Vt ieee80211com
78 structure and one or more
79 .Vt ieee80211vap
80 structures.
81 Vaps are created with the
82 .Dv SIOCIFCREATE2
83 request.
84 This results in a call into the driver's
85 .Vt ic_vap_create
86 method where the driver can decide if the request should be accepted.
87 .Pp
88 The vap creation process is done in three steps.
89 First the driver allocates the data structure with
90 .Xr malloc 9 .
91 This data structure must have an
92 .Vt ieee80211vap
93 structure at the front but is usually extended with driver-private state.
94 Next the vap is setup with a call to
95 .Fn ieee80211_vap_setup .
96 This request initializes
97 .Nm net80211
98 state but does not activate the interface.
99 The driver can then override methods setup by
100 .Nm net80211
101 and setup driver resources before finally calling
102 .Fn ieee80211_vap_attach
103 to complete the process.
104 Both these calls must be done without holding any driver locks as
105 work may require the process block/sleep.
106 .Pp
107 A vap is deleted when an
108 .Dv SIOCIFDESTROY
109 ioctl request is made or when the device detaches (causing all
110 associated vaps to automatically be deleted).
111 Delete requests cause the
112 .Vt ic_vap_delete
113 method to be called.
114 Drivers must quiesce the device before calling
115 .Fn ieee80211_vap_detach
116 to deactivate the vap and isolate it from activities such as requests
117 from user applications.
118 The driver can then reclaim resources held by the vap and re-enable
119 device operation.
120 The exact procedure for quiesceing a device is unspecified but typically
121 it involves blocking interrupts and stopping transmit and receive
122 processing.
123 .Sh MULTI-VAP OPERATION
124 Drivers are responsible for deciding if multiple vaps can be created
125 and how to manage them.
126 Whether or not multiple concurrent vaps can be supported depends on a
127 device's capabilities.
128 For example, multiple hostap vaps can usually be supported but many
129 devices do not support assigning each vap a unique BSSID.
130 If a device supports hostap operation it can usually support concurrent
131 station mode vaps but possibly with limitations such as losing support
132 for hardware beacon miss support.
133 Devices that are capable of hostap operation and can send and receive
134 4-address frames should be able to support WDS vaps together with an
135 ap vap.
136 But in contrast some devices cannot support WDS vaps without at least one
137 ap vap (this however can be finessed by forcing the ap vap to not transmit
138 beacon frames).
139 All devices should support the creation of any number of monitor mode vaps
140 concurrent with other vaps but it is the responsibility of the driver to
141 allow this.
142 .Pp
143 An important consequence of supporting multiple concurrent vaps is that
144 a driver's
145 .Vt iv_newstate
146 method must be written to handle being called for each vap.
147 Where necessary, drivers must track private state for all vaps
148 and not just the one whose state is being changed (e.g. for
149 handling beacon timers the driver may need to know if all vaps
150 that beacon are stopped before stopping the hardware timers).
151 .Sh SEE ALSO
152 .Xr ieee80211 9 ,
153 .Xr ifnet 9 ,
154 .Xr malloc 9