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