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