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