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.Dd August 4, 2009 27.Dt IEEE8021_VAP 9 28.Os 29.Sh NAME 30.Nm net80211_vap 31.Nd 802.11 network layer virtual radio support 32.Sh SYNOPSIS 33.In net80211/ieee80211_var.h 34.Ft int 35.Fo ieee80211_vap_setup 36.Fa "struct ieee80211com *" 37.Fa "struct ieee80211vap *" 38.Fa "const char name[IFNAMSIZ]" 39.Fa "int unit" 40.Fa "int opmode" 41.Fa "int flags" 42.Fa "const uint8_t bssid[IEEE80211_ADDR_LEN]" 43.Fa "const uint8_t macaddr[IEEE80211_ADDR_LEN]" 44.Fc 45.\" 46.Ft int 47.Fo ieee80211_vap_attach 48.Fa "struct ieee80211vap *" 49.Fa "ifm_change_cb_t media_change" 50.Fa "ifm_stat_cb_t media_stat" 51.Fc 52.\" 53.Ft void 54.Fn ieee80211_vap_detach "struct ieee80211vap *" 55.Sh DESCRIPTION 56The 57.Nm net80211 58software layer provides a support framework for drivers that includes 59a virtual radio API that is exported to 60users through network interfaces (aka vaps) that are cloned from the 61underlying device. 62These interfaces have an operating mode 63(station, adhoc, hostap, wds, monitor, etc.\&) 64that is fixed for the lifetime of the interface. 65Devices that can support multiple concurrent interfaces allow 66multiple vaps to be cloned. 67.Pp 68The virtual radio interface defined by the 69.Nm net80211 70layer means that drivers must be structured to follow specific rules. 71Drivers that support only a single interface at any time must still 72follow these rules. 73.Pp 74The virtual radio architecture splits state between a single per-device 75.Vt ieee80211com 76structure and one or more 77.Vt ieee80211vap 78structures. 79Vaps are created with the 80.Dv SIOCIFCREATE2 81request. 82This results in a call into the driver's 83.Vt ic_vap_create 84method where the driver can decide if the request should be accepted. 85.Pp 86The vap creation process is done in three steps. 87First the driver allocates the data structure with 88.Xr malloc 9 . 89This data structure must have an 90.Vt ieee80211vap 91structure at the front but is usually extended with driver-private state. 92Next the vap is setup with a call to 93.Fn ieee80211_vap_setup . 94This request initializes 95.Nm net80211 96state but does not activate the interface. 97The driver can then override methods setup by 98.Nm net80211 99and setup driver resources before finally calling 100.Fn ieee80211_vap_attach 101to complete the process. 102Both these calls must be done without holding any driver locks as 103work may require the process block/sleep. 104.Pp 105A vap is deleted when an 106.Dv SIOCIFDESTROY 107ioctl request is made or when the device detaches (causing all 108associated vaps to automatically be deleted). 109Delete requests cause the 110.Vt ic_vap_delete 111method to be called. 112Drivers must quiesce the device before calling 113.Fn ieee80211_vap_detach 114to deactivate the vap and isolate it from activities such as requests 115from user applications. 116The driver can then reclaim resources held by the vap and re-enable 117device operation. 118The exact procedure for quiescing a device is unspecified but typically 119it involves blocking interrupts and stopping transmit and receive 120processing. 121.Sh MULTI-VAP OPERATION 122Drivers are responsible for deciding if multiple vaps can be created 123and how to manage them. 124Whether or not multiple concurrent vaps can be supported depends on a 125device's capabilities. 126For example, multiple hostap vaps can usually be supported but many 127devices do not support assigning each vap a unique BSSID. 128If a device supports hostap operation it can usually support concurrent 129station mode vaps but possibly with limitations such as losing support 130for hardware beacon miss support. 131Devices that are capable of hostap operation and can send and receive 1324-address frames should be able to support WDS vaps together with an 133ap vap. 134But in contrast some devices cannot support WDS vaps without at least one 135ap vap (this however can be finessed by forcing the ap vap to not transmit 136beacon frames). 137All devices should support the creation of any number of monitor mode vaps 138concurrent with other vaps but it is the responsibility of the driver to 139allow this. 140.Pp 141An important consequence of supporting multiple concurrent vaps is that 142a driver's 143.Vt iv_newstate 144method must be written to handle being called for each vap. 145Where necessary, drivers must track private state for all vaps 146and not just the one whose state is being changed (e.g. for 147handling beacon timers the driver may need to know if all vaps 148that beacon are stopped before stopping the hardware timers). 149.Sh SEE ALSO 150.Xr ieee80211 9 , 151.Xr ifnet 9 , 152.Xr malloc 9 153