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