xref: /freebsd/share/man/man9/ieee80211_output.9 (revision fe75646a0234a261c0013bf1840fdac4acaf0cec)
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