share/man/man9/ieee80211_output.9

   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: head/share/man/man9/ieee80211_output.9 233648 2012-03-29 05:02:12Z eadler $
  28 .\" $Id: ieee80211_output.9,v 1.5 2004/03/04 12:31:18 bruce Exp $
  29 .\"
  30 .Dd May 25, 2016
  31 .Dt IEEE80211_OUTPUT 9
  32 .Os
  33 .Sh NAME
  34 .Nm ieee80211_output
  35 .Nd software 802.11 stack output functions
  36 .Sh SYNOPSIS
  37 .In net/if.h
  38 .In net/if_media.h
  39 .In netproto/802_11/ieee80211_var.h
  40 .\"
  41 .Ft int
  42 .Fn M_WME_GETAC "struct mbuf *"
  43 .\"
  44 .Ft int
  45 .Fn M_SEQNO_GET "struct mbuf *"
  46 .\"
  47 .Ft void
  48 .Fo ieee80211_process_callback
  49 .Fa "struct ieee80211_node *"
  50 .Fa "struct mbuf *"
  51 .Fa "int"
  52 .Fc
  53 .Sh DESCRIPTION
  54 The
  55 .Nm net80211
  56 layer that supports 802.11 device drivers handles most of the
  57 work required to transmit frames.
  58 Drivers usually receive fully-encapsulated 802.11 frames that
  59 have been classified and assigned a transmit priority;
  60 all that is left is to do
  61 crypto encapsulation,
  62 prepare any hardware-specific state,
  63 and
  64 push the packet out to the device.
  65 Outbound frames are either generated by the
  66 .Nm net80211
  67 layer (e.g. management frames) or are passed down
  68 from upper layers through the
  69 .Xr ifnet 9
  70 transmit queue.
  71 Data frames passed down for transmit flow through
  72 .Nm net80211
  73 which handles aggregation, 802.11 encapsulation, and then
  74 dispatches the frames to the driver through it's transmit queue.
  75 .Pp
  76 There are two control paths by which frames reach a driver for transmit.
  77 Data packets are queued to the device's
  78 .Vt if_snd
  79 queue and the driver's
  80 .Vt if_start
  81 method is called.
  82 Other frames are passed down using the
  83 .Vt ic_raw_xmit
  84 method without queueing (unless done by the driver).
  85 The raw transmit path may include data frames from user applications
  86 that inject them through
  87 .Xr bpf 4
  88 and NullData frames generated by
  89 .Nm net80211
  90 to probe for idle stations (when operating as an access point).
  91 .Pp
  92 .Nm net80211
  93 handles all state-related bookkeeping and management for the handling
  94 of data frames.
  95 Data frames are only transmit for a vap in the
  96 .Dv IEEE80211_S_RUN
  97 state; there is no need, for example, to check for frames sent down
  98 when CAC or CSA is active.
  99 Similarly,
 100 .Nm net80211
 101 handles activities such as background scanning and power save mode,
 102 frames will not be sent to a driver unless it is operating on the
 103 BSS channel with
 104 .Dq full power .
 105 .Pp
 106 All frames passed to a driver for transmit hold a reference to a
 107 node table entry in the
 108 .Vt m_pkthdr.rcvif
 109 field.
 110 The node is associated with the frame destination.
 111 Typically it is the receiver's entry but in some situations it may be
 112 a placeholder entry or the
 113 .Dq next hop station
 114 (such as in a mesh network).
 115 In all cases the reference must be reclaimed with
 116 .Fn ieee80211_free_node
 117 when the transmit work is completed.
 118 The rule to remember is:
 119 .Nm net80211
 120 passes responsibility for the
 121 .Vt mbuf
 122 and
 123 .Dq node reference
 124 to the driver with each frame it hands off for transmit.
 125 .Sh PACKET CLASSIFICATION
 126 All frames passed by
 127 .Nm net80211
 128 for transmit are assigned a priority based on any vlan tag
 129 assigned to the receiving station and/or any Diffserv setting
 130 in an IP or IPv6 header.
 131 If both vlan and Diffserv priority are present the higher of the
 132 two is used.
 133 If WME/WMM is being used then any ACM policy (in station mode) is
 134 also enforced.
 135 The resulting AC is attached to the mbuf and may be read back using the
 136 .Fn M_WME_GETAC
 137 macro.
 138 .Pp
 139 PAE/EAPOL frames are tagged with an
 140 .Dv M_EAPOL
 141 mbuf flag; drivers should transmit them with care, usually by
 142 using the transmit rate for management frames.
 143 Multicast/broadcast frames are marked with the
 144 .Dv M_MCAST
 145 mbuf flag.
 146 Frames coming out of a station's power save queue and that have
 147 more frames immediately following are marked with the
 148 .Dv M_MORE_DATA
 149 mbuf flag.
 150 Such frames will be queued consecutively in the driver's
 151 .Vt if_snd
 152 queue and drivers should preserve the ordering when passing
 153 them to the device.
 154 .Sh FRAGMENTED FRAMES
 155 The
 156 .Nm net80211
 157 layer will fragment data frames according to the setting of
 158 .Vt iv_fragthreshold
 159 if a driver marks the
 160 .Dv IEEE80211_C_TXFRAG
 161 capability.
 162 Fragmented frames are placed
 163 in the devices transmit queue with the fragments chained together with
 164 .Vt m_nextpkt .
 165 Each frame is marked with the
 166 .Dv M_FRAG
 167 mbuf flag, and the first and last are marked with
 168 .Dv M_FIRSTFRAG
 169 and
 170 .Dv M_LASTFRAG ,
 171 respectively.
 172 Drivers are expected to process all fragments or none.
 173 .Sh TRANSMIT CALLBACKS
 174 Frames sent by
 175 .Nm net80211
 176 may be tagged with the
 177 .Dv M_TXCB
 178 mbuf flag to indicate a callback should be done
 179 when their transmission completes.
 180 The callback is done using
 181 .Fn ieee80211_process_callback
 182 with the last parameter set to a non-zero value if an error occurred
 183 and zero otherwise.
 184 Note
 185 .Nm net80211
 186 understands that drivers may be incapable of determining status;
 187 a device may not report if an ACK frame is received and/or a device may queue
 188 transmit requests in its hardware and only report status on whether
 189 the frame was successfully queued.
 190 .Sh SEE ALSO
 191 .Xr bpf 4 ,
 192 .Xr ieee80211 9 ,
 193 .Xr ieee80211_crypto_encap 9 ,
 194 .Xr ifnet 9