1 files changed, 147 insertions, 104 deletions
diff --git a/share/man/man9/ieee80211_output.9 b/share/man/man9/ieee80211_output.9
index f553c4f..c2f9667 100644
--- a/share/man/man9/ieee80211_output.9
+++ b/share/man/man9/ieee80211_output.9
@@ -27,125 +27,168 @@
 .\" $FreeBSD$
 .\" $Id: ieee80211_output.9,v 1.5 2004/03/04 12:31:18 bruce Exp $
 .\"
-.Dd March 2, 2004
+.Dd August 4, 2009
 .Dt IEEE80211_OUTPUT 9
 .Os
 .Sh NAME
-.Nm ieee80211_encap , ieee80211_add_rates ,
-.Nm ieee80211_add_xrates , ieee80211_send_mgmt
+.Nm ieee80211_output
 .Nd software 802.11 stack output functions
 .Sh SYNOPSIS
 .In net80211/ieee80211_var.h
-.In net80211/ieee80211_proto.h
-.Ft struct mbuf *
-.Fo ieee80211_encap
-.Fa "struct ifnet *ifp" "struct mbuf *m" "struct ieee80211_node **pni"
-.Fc
-.Ft u_int8_t *
-.Fn ieee80211_add_rates "u_int8_t *frm" "const struct ieee80211_rateset *rs"
-.Ft u_int8_t *
-.Fn ieee80211_add_xrates "u_int8_t *frm" "const struct ieee80211_rateset *rs"
+.\"
+.Ft int
+.Fn M_WME_GETAC "struct mbuf *"
+.\"
 .Ft int
-.Fo ieee80211_send_mgmt
-.Fa "struct ieee80211com *ic" "struct ieee80211_node *ni" "int type" "int arg"
+.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
-These functions handle the encapsulation and transmission of 802.11 frames
-within the software 802.11 stack.
-.Pp
 The
-.Fn ieee80211_encap
-function encapsulates an outbound data frame contained within the
-mbuf chain
-.Fa m
-from the interface
-.Fa ifp .
-The argument
-.Fa *pni
-is a reference to the destination node.
+.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
-If the function is successful, the mbuf chain is updated with the
-802.11 frame header prepended, and a pointer to the head of the chain
-is returned.
-If an error occurs,
-.Dv NULL
-will be returned, and
-.Fa *pni
-is also set to
-.Dv NULL .
-The caller is responsible for freeing the node reference if
-.Fa *pni
-is
-.Pf non- Dv NULL
-on return.
-The convention is that
-.Va ic_bss
-is not reference counted; the caller is responsible for maintaining this
-reference count.
+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
-.\"
-The
-.Fn ieee80211_add_rates
-utility function is used to add the rate set element
-.Fa *rs
-to the frame
-.Fa frm .
-A pointer to the location in the buffer after the addition of the rate set
-is returned.
-It is typically used when constructing management frames from within the
-software 802.11 stack.
+.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 will
+.Dq full power .
 .Pp
-.\"
-The
-.Fn ieee80211_add_xrates
-utility function is used to add the extended rate set element
-.Fa *rs
-to the frame
-.Fa frm .
-A pointer to the location in the buffer after the addition of the rate set
-is returned.
-It is typically used when constructing management frames from within the
-software 802.11 stack in 802.11g mode.
+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
-.Fn ieee80211_send_mgmt
-function transmits a management frame on the interface
-.Fa ic
-to the destination node
-.Fa ni
-of type
-.Fa type .
-.Pp
-The argument
-.Fa arg
-specifies either a sequence number for authentication operations,
-a status code for [re]association operations,
-or a reason for deauthentication and deassociation operations.
-.Pp
-Nodes other than
-.Va ic_bss
-have their reference count incremented to reflect their use for an
-indeterminate amount of time.
-This reference is freed when the function returns.
-.Pp
-The function returns 0 if successful; if temporary buffer space is not
-available, the function returns
-.Er ENOMEM .
-.\"
+.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
-.Sh HISTORY
-The
-.Nm ieee80211
-series of functions first appeared in
-.Nx 1.5 ,
-and were later ported to
-.Fx 4.6 .
-.Sh AUTHORS
-.An -nosplit
-This manual page was written by
-.An Bruce M. Simpson Aq bms@FreeBSD.org
-and
-.An Darron Broad Aq darron@kewl.org .