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