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