import rssadapt man page from NetBSD.

ok jmc@ millert@ jsg@ deraadt@

2 files changed, 424 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 5ada26e4aba..44d3c524681 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.89 2005/02/18 16:15:32 pedro Exp $
+#	$OpenBSD: Makefile,v 1.90 2005/03/01 19:22:10 damien Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -15,7 +15,7 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	mountroothook_establish.9 mutex.9 namei.9 \
 	panic.9 pfind.9 physio.9 pmap.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
-	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 \
+	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 \
 	shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \
 	style.9 syscall.9 systrace.9 \
 	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 \
@@ -158,6 +158,11 @@ MLINKS+=random.9 add_true_randomness.9 \
 	random.9 add_audio_randomness.9 \
 	random.9 get_random_bytes.9 \
 	random.9 arc4random.9
+MLINKS+=rssadapt.9 ieee80211_rssadapt_choose.9 \
+	rssadapt.9 ieee80211_rssadapt_input.9 \
+	rssadapt.9 ieee80211_rssadapt_lower_rate.9 \
+	rssadapt.9 ieee80211_rssadapt_raise_rate.9 \
+	rssadapt.9 ieee80211_rssadapt_updatestats.9
 MLINKS+=pfind.9 pgfind.9
 MLINKS+=pmap.9 pmap_init.9 pmap.9 pmap_enter.9 pmap.9 pmap_remove.9 \
 	pmap.9 pmap_unwire.9 pmap.9 pmap_protect.9 pmap.9 pmap_page_protect.9 \
diff --git a/share/man/man9/rssadapt.9 b/share/man/man9/rssadapt.9
new file mode 100644
index 00000000000..04dae0914b4
--- /dev/null
+++ b/share/man/man9/rssadapt.9
@@ -0,0 +1,417 @@
+.\"	$OpenBSD: rssadapt.9,v 1.1 2005/03/01 19:22:10 damien Exp $
+.\"     $NetBSD: rssadapt.9,v 1.4 2004/12/08 18:35:56 peter Exp $
+.\"
+.\" Copyright (c) 2004 David Young.  All rights reserved.
+.\"
+.\" This code is by David Young.
+.\"
+.\" 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.
+.\" 3. The name of David Young may not be used to endorse or promote
+.\"    products derived from this software without specific prior
+.\"    written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY David Young ``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 David
+.\" Young 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.
+.\"
+.Dd March 23, 2004
+.Dt RSSADAPT 9
+.Os
+.Sh NAME
+.Nm rssadapt ,
+.Nm ieee80211_rssadapt_choose ,
+.Nm ieee80211_rssadapt_input ,
+.Nm ieee80211_rssadapt_lower_rate ,
+.Nm ieee80211_rssadapt_raise_rate ,
+.Nm ieee80211_rssadapt_updatestats
+.Nd rate adaptation based on received signal strength
+.Sh SYNOPSIS
+.In net80211/ieee80211_var.h
+.In net80211/ieee80211_rssadapt.h
+.Ft void
+.Fn ieee80211_rssadapt_input "struct ieee80211com *ic" \
+"struct ieee80211_node *ni" "struct ieee80211_rssadapt *ra" "int rssi"
+.Ft void
+.Fn ieee80211_rssadapt_lower_rate "struct ieee80211com *ic" \
+"struct ieee80211_node *ni" "struct ieee80211_rssadapt *ra" \
+"struct ieee80211_rssdesc *id"
+.Ft void
+.Fn ieee80211_rssadapt_raise_rate "struct ieee80211com *ic" \
+"struct ieee80211_rssadapt *ra" "struct ieee80211_rssdesc *id"
+.Ft void
+.Fn ieee80211_rssadapt_updatestats "struct ieee80211_rssadapt *ra"
+.Ft int
+.Fn ieee80211_rssadapt_choose "struct ieee80211_rssadapt *ra" \
+"struct ieee80211_rateset *rs" "struct ieee80211_frame *wh" "u_int len" \
+"int fixed_rate" "const char *dvname" "int do_not_adapt"
+.Sh DESCRIPTION
+The
+.Nm
+module provides rapid adaptation of transmission data rate to 802.11
+device drivers based on received-signal strength
+.Pq RSS .
+A driver needs only to provide
+.Nm
+with indications of RSS and failure/success of transmissions for
+each 802.11 client or peer.
+For each transmit packet,
+.Nm
+chooses the transmission data rate that offers the best expected
+throughput, given the packet's length and destination.
+.Pp
+.Nm
+models an 802.11 channel very simply
+.Po
+see also the
+.Sx BUGS
+section
+.Pc .
+It assumes that the packet-error rate
+.Pq PER
+is determined by the signal-to-noise ratio
+.Pq S/N
+at the receiver, the transmission data rate, and the packet length.
+The S/N determines the choice of data rate that yields the lowest
+PER for all packets of a certain length.
+.Sh FUNCTIONS
+.Bl -tag -width Ds -compact
+.It Fn ieee80211_rssadapt_choose "ra" "rs" "wh" "len" "fixed_rate" "dvname" \
+"do_not_adapt"
+.Pp
+Choose the transmission data rate for a packet.
+.Pp
+.Bl -tag -width "do_not_adapt" -compact
+.It Fa ra
+Ordinarily, the
+.Nm
+state object belonging to the node which is the packet destination.
+However, if the destination is a broadcast/multicast address, then
+.Fa ra
+belongs to the BSS node,
+.Va ic-\*(Gtic_bss .
+.It Fa rs
+A list of eligible data rates for the node; for example, the
+rates negotiated when the node associated with the network.
+.It Fa len
+The packet length in bytes, including the 802.11 header and
+frame check sequence
+.Pq FCS .
+.It Fa fixed_rate
+If the operator has set the data rate using, for example,
+.Ic "ifconfig wi0 media ds1" ,
+then
+.Fa fixed_rate
+tells the index of that rate in
+.Fa rs .
+.Nm
+obeys a fixed data rate whenever the 802.11 standard allows it:
+sometimes the standard requires multicast/broadcast packets to be
+transmitted at a so-called
+.Dq basic rate .
+.It Fa dvname
+The device driver uses
+.Fa dvname
+to indicate the name of the
+interface for the purpose of diagnostic and debug messages.
+The driver sets
+.Fa dvname
+to
+.Dv NULL
+when no messages are desired.
+.It Fa do_not_adapt
+If
+.Fa do_not_adapt
+is non-zero, then
+.Fn ieee80211_rssadapt_choose
+will choose the highest rate in
+.Fa rs
+that suits the destination, regardless of the RSS.
+.El
+The return value of
+.Fn ieee80211_rssadapt_choose
+is an index into
+.Fa rs ,
+indicating its choice of transmit data rate.
+.Pp
+.It Fn ieee80211_rssadapt_input "ic" "ni" "ra" "rssi"
+The RSS serves as a rough estimate of the S/N at each node.
+A driver provides RSS updates using
+.Fn ieee80211_rssadapt_input ,
+whose arguments are:
+.Pp
+.Bl -tag -width "rssi" -compact
+.It Fa ic
+The wireless interface's 802.11 state object.
+.It Fa ni
+The 802.11 node whose RSS the driver is updating.
+.It Fa ra
+The node's
+.Nm
+state object.
+.It Fa rssi
+The node's received signal strength indication.
+The range of
+.Fa rssi
+is from 0 to 255.
+.El
+.Pp
+.It Fn ieee80211_rssadapt_lower_rate "ic" "ni" "ra" "id"
+.It Fn ieee80211_rssadapt_raise_rate "ic" "ra" "id"
+Drivers call
+.Fn ieee80211_rssadapt_raise_rate
+and
+.Fn ieee80211_rssadapt_lower_rate
+to indicate transmit successes and failures, respectively.
+.Pp
+.Bl -tag -width Ds -compact
+.It Fa ic
+The 802.11 state object.
+.It Fa ni
+The neighbor to whom the driver transmitted.
+.It Fa ra
+The neighbor's
+.Nm
+state object.
+.It Fa id
+Displays statistics on the transmission attempt.
+.El
+.Pp
+.It Fn ieee80211_rssadapt_updatestats "ra"
+An 802.11 node is eligible for its RSS thresholds to decay every
+1/10 to 10 seconds.
+It is eligible more often (every 1/10 second) at high packet rates,
+and less often (every 10 seconds) at low packet rates.
+A driver assists
+.Nm
+in tracking the exponential-average packet rate by calling
+.Fn ieee80211_rssadapt_updatestats
+every 1/10th second for each node's
+.Vt ieee80211_rssadapt
+object.
+.Pp
+.Bl -tag -width Ds -compact
+.It Fa ra
+The neighbor's
+.Nm
+state object.
+.El
+.El
+.Sh ALGORITHM
+.Nm
+monitors the RSS from neighboring 802.11 nodes, recording the
+exponential average RSS in each neighbor's
+.Vt ieee80211_rssadapt
+structure.
+.Nm
+uses transmit success/failure feedback from the
+device driver to fill a table of RSS thresholds.
+The table is indexed by packet size,
+.Va L ,
+and a data rate,
+.Va R ,
+to find out the minimum exponential-average RSS that a node must show before
+.Nm
+will indicate that a packet
+.Va L
+bytes long can be transmitted R bits per second with optimal expected
+throughput.
+.Pp
+When the driver indicates a unicast packet is transmitted unsuccessfully
+.Po
+that is, the NIC received no ACK for the packet
+.Pc ,
+.Nm
+will move the corresponding RSS threshold toward the exponential
+average RSSI at the time of transmission.
+Thus several consecutive transmit failures for the same
+.Ao
+.Va L ,
+.Va R
+.Ac
+tuple will ensure that the RSS threshold rises high enough that
+rate
+.Va R
+is abandoned for packets
+.Va L
+bytes long.
+When the driver indicates a successful transmission,
+the RSS threshold corresponding to the same packet length, but the
+next higher data rate, is lowered slightly.
+The RSS threshold is said to
+.Dq decay .
+This ensures that occasionally
+.Nm
+indicates the driver should try the next higher data rate,
+just in case conditions at the receiver have changed
+.Po
+for example, noise levels have fallen
+.Pc
+and a higher data rate can be supported at the same RSS level.
+.Pp
+The rate of decay is controlled.
+In an interval of 1/10th second
+to 10 seconds, only one RSS threshold per neighbor may decay.
+The interval is connected to the exponential-average rate that packets
+are being transmitted.
+At high packet rates, the interval is shortest.
+It is longest at low packet rates.
+The rationale for this is that RSS thresholds should not decay
+rapidly if there is no information from packet transmissions to
+counteract their decay.
+.Sh DATA STRUCTURES
+An
+.Vt ieee80211_rssdesc
+describes a transmission attempt.
+.Bd -literal -offset indent
+struct ieee80211_rssdesc {
+        u_int                    id_len;
+        u_int                    id_rateidx;
+        struct ieee80211_node   *id_node;
+        u_int8_t                 id_rssi;
+};
+.Ed
+.Pp
+.Fa id_len
+is the length, in bytes, of the transmitted packet.
+.Fa id_node
+points to the neighbor's
+.Vt ieee8021_node ,
+and
+.Fa id_rssi
+is the exponential-average RSS at the time the packet was
+transmitted.
+.Fa id_rateidx
+is an index into the destination neighbor's rate-set,
+.Fa id_node-\*(Gtni_rates ,
+indicating the transmit data rate for the packet.
+.Pp
+.Vt ieee80211_rssadapt
+contains the rate-adaptation state for a neighboring 802.11 node.
+Ordinarily a driver will
+.Dq subclass
+.Vt ieee80211_node .
+The
+.Vt ieee80211_rssadapt
+structure will be a subclass member.
+In this way, every node's
+.Nm
+condition is independently tracked and stored in its node object.
+.Bd -literal -offset 4n
+struct ieee80211_rssadapt {
+        u_int16_t               ra_avg_rssi;
+        u_int32_t               ra_nfail;
+        u_int32_t               ra_nok;
+        u_int32_t               ra_pktrate;
+        u_int16_t               ra_rate_thresh[IEEE80211_RSSADAPT_BKTS]
+                                              [IEEE80211_RATE_SIZE];
+        struct timeval          ra_last_raise;
+        struct timeval          ra_raise_interval;
+};
+.Ed
+.Pp
+.Fa ra_avg_rssi
+is the exponential-average RSS, shifted left 8 bits.
+.Fa ra_nfail
+indicates the number of transmit failures in the current update interval;
+.Fa ra_nok
+the number of transmit successes in the current update interval.
+.Fa ra_pktrate
+indicates the exponential average number of transmit failure/success
+indications over past update intervals.
+This approximates the rate of packet-transmission.
+.Fa ra_rate_thresh
+contains RSS thresholds that are indexed by
+.Aq "packet length, data rate"
+tuples.
+When this node's exponential-average RSS exceeds
+.Fa ra_rate_thresh[i][j] ,
+then packets at most 128 x 8^i bytes long are eligible to be
+transmitted at the rate indexed by j.
+.Pp
+.Fa ra_last_raise
+and
+.Fa ra_raise_interval
+are used to control the rate that RSS thresholds
+.Dq decay .
+.Fa ra_last_raise
+indicates when
+.Fn ieee80211_rssadapt_raise_rate
+was last called and
+.Fa ra_raise_interval
+indicates the minimum period between consecutive calls to
+.Fn ieee80211_rssadapt_raise_rate .
+If
+.Fn ieee80211_rssadapt_raise_rate
+is called more than once in any period, the second and subsequent
+calls are ignored.
+.Sh CODE REFERENCES
+This section describes places within the
+.Ox
+source tree where actual code implementing or using
+.Nm
+can be found.
+All pathnames are relative to
+.Pa /usr/src .
+.Pp
+The code for
+.Nm
+is in the file
+.Pa sys/net80211/ieee80211_rssadapt.c .
+.Pp
+.Xr ral 4
+contains a reference implementation.
+See
+.Pa sys/dev/ic/ral.c .
+.Sh SEE ALSO
+.Xr ral 4
+.Rs
+.%A Javier del Prado Pavon
+.%A Sunghyun Choi
+.%T "Link Adaptation Strategy for IEEE 802.11 WLAN via Received Signal \
+Strength Measurement"
+.%J "ICC'03"
+.%P pp. 1108-1113
+.%C Anchorage, Alaska
+.%D May 2003
+.Re
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx
+and was ported to
+.Ox
+by
+.An Todd C. Miller Aq millert@OpenBSD.org
+.Sh AUTHORS
+.An David Young Aq dyoung@NetBSD.org
+.Sh BUGS
+To cope with interference from microwave ovens, frequency-hopping
+radios, and other sources of RF pulse-trains and bursts,
+.Nm
+should adapt the fragmentation threshold as well as the data rate.
+.Pp
+For improved throughput,
+.Nm
+should indicate to drivers when they should use the 802.11b
+short-preamble.
+.Pp
+The constants in
+.Fn ieee80211_rssadapt_updatestats
+should be configurable.