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