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