path: root/share/man/man9/ieee80211_output.9

.\"
.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
.\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\" $Id: ieee80211_output.9,v 1.5 2004/03/04 12:31:18 bruce Exp $
.\"
.Dd March 29, 2010
.Dt IEEE80211_OUTPUT 9
.Os
.Sh NAME
.Nm ieee80211_output
.Nd software 802.11 stack output functions
.Sh SYNOPSIS
.In net80211/ieee80211_var.h
.\"
.Ft int
.Fn M_WME_GETAC "struct mbuf *"
.\"
.Ft int
.Fn M_SEQNO_GET "struct mbuf *"
.\"
.Ft struct ieee80211_key *
.Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *"
.\"
.Ft void
.Fo ieee80211_process_callback
.Fa "struct ieee80211_node *"
.Fa "struct mbuf *"
.Fa "int"
.Fc
.Sh DESCRIPTION
The
.Nm net80211
layer that supports 802.11 device drivers handles most of the
work required to transmit frames.
Drivers usually receive fully-encapsulated 802.11 frames that
have been classified and assigned a transmit priority;
all that is left is to do
crypto encapsulation,
prepare any hardware-specific state,
and
push the packet out to the device.
Outbound frames are either generated by the
.Nm net80211
layer (e.g. management frames) or are passed down
from upper layers through the
.Xr ifnet 9
transmit queue.
Data frames passed down for transmit flow through
.Nm net80211
which handles aggregation, 802.11 encapsulation, and then
dispatches the frames to the driver through it's transmit queue.
.Pp
There are two control paths by which frames reach a driver for transmit.
Data packets are queued to the device's
.Vt if_snd
queue and the driver's
.Vt if_start
method is called.
Other frames are passed down using the
.Vt ic_raw_xmit
method without queueing (unless done by the driver).
The raw transmit path may include data frames from user applications
that inject them through
.Xr bpf 4
and NullData frames generated by
.Nm net80211
to probe for idle stations (when operating as an access point).
.Pp
.Nm net80211
handles all state-related bookkeeping and management for the handling
of data frames.
Data frames are only transmit for a vap in the
.Dv IEEE80211_S_RUN
state; there is no need, for example, to check for frames sent down
when CAC or CSA is active.
Similarly,
.Nm net80211
handles activities such as background scanning and power save mode,
frames will not be sent to a driver unless it is operating on the
BSS channel with
.Dq full power .
.Pp
All frames passed to a driver for transmit hold a reference to a
node table entry in the
.Vt m_pkthdr.rcvif
field.
The node is associated with the frame destination.
Typically it is the receiver's entry but in some situations it may be
a placeholder entry or the 
.Dq next hop station
(such as in a mesh network).
In all cases the reference must be reclaimed with
.Fn ieee80211_free_node
when the transmit work is completed.
The rule to remember is: 
.Nm net80211
passes responsibility for the
.Vt mbuf
and
.Dq node reference
to the driver with each frame it hands off for transmit.
.Sh PACKET CLASSIFICATION
All frames passed by
.Nm net80211
for transmit are assigned a priority based on any vlan tag
assigned to the receiving station and/or any Diffserv setting
in an IP or IPv6 header.
If both vlan and Diffserv priority are present the higher of the
two is used.
If WME/WMM is being used then any ACM policy (in station mode) is 
also enforced.
The resulting AC is attached to the mbuf and may be read back using the
.Fn M_WME_GETAC
macro.
.Pp
PAE/EAPOL frames are tagged with an
.Dv M_EAPOL
mbuf flag; drivers should transmit them with care, usually by
using the transmit rate for management frames.
Multicast/broadcast frames are marked with the
.Dv M_MCAST
mbuf flag.
Frames coming out of a station's power save queue and that have
more frames immediately following are marked with the
.Dv M_MORE_DATA
mbuf flag.
Such frames will be queued consecutively in the driver's
.Vt if_snd
queue and drivers should preserve the ordering when passing
them to the device.
.Sh FRAGMENTED FRAMES
The
.Nm net80211
layer will fragment data frames according to the setting of
.Vt iv_fragthreshold
if a driver marks the
.Dv IEEE80211_C_TXFRAG
capability.
Fragmented frames are placed
in the devices transmit queue with the fragments chained together with
.Vt m_nextpkt .
Each frame is marked with the
.Dv M_FRAG
mbuf flag, and the first and last are marked with
.Dv M_FIRSTFRAG
and
.Dv M_LASTFRAG ,
respectively.
Drivers are expected to process all fragments or none.
.Sh TRANSMIT CALLBACKS
Frames sent by
.Nm net80211
may be tagged with the
.Dv M_TXCB
mbuf flag to indicate a callback should be done
when their transmission completes.
The callback is done using
.Fn ieee80211_process_callback
with the last parameter set to a non-zero value if an error occurred
and zero otherwise.
Note 
.Nm net80211
understands that drivers may be incapable of determining status;
a device may not report if an ACK frame is received and/or a device may queue
transmit requests in its hardware and only report status on whether
the frame was successfully queued.
.Sh SEE ALSO
.Xr bpf 4 ,
.Xr ieee80211 9 ,
.Xr ifnet 9