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