407 lines
12 KiB
Groff
407 lines
12 KiB
Groff
.\" $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 18n -compact
|
|
.It Fn ieee80211_rssadapt_choose "ra" "rs" "wh" "len" "fixed_rate" "dvname" \
|
|
"do_not_adapt"
|
|
Choose the transmission data rate for a packet.
|
|
.Bl -tag -width "do_not_adapt" -compact
|
|
.It Fa ra
|
|
ordinarily, the
|
|
.Nm
|
|
state object belonging to the node who is the packet destination.
|
|
However, if the destination is a broadcast/multicast address, then
|
|
.Fa ra
|
|
belongs to the BSS node,
|
|
.Va ic-\*[Gt]ic_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 .
|
|
.Fn ieee80211_rssadapt_choose
|
|
.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.
|
|
.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
|
|
.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; and
|
|
.It Fa rssi
|
|
the node's received signal strength indication.
|
|
The range of
|
|
.Fa rssi
|
|
is from 0 to 255.
|
|
.El
|
|
.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.
|
|
.Bl -tag -width "ni" -compact
|
|
.It Fa ic
|
|
is the 802.11 state object,
|
|
.It Fa ni
|
|
is the neighbor to whom the driver transmitted,
|
|
.It Fa ra
|
|
is the neighbor's
|
|
.Nm
|
|
state object, and
|
|
.It Fa id
|
|
tells statistics on the transmission attempt.
|
|
.El
|
|
.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.
|
|
.Bl -tag -width "ra" -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.
|
|
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.
|
|
.Pp
|
|
.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
|
|
tells the length, in bytes, of the transmitted packet.
|
|
.Fa id_node
|
|
points at the neighbor's
|
|
.Vt ieee8021_node ,
|
|
and
|
|
.Fa id_rssi
|
|
tells 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-\*[Gt]ni_rates ,
|
|
indicating the transmit data rate for the packet.
|
|
.Pp
|
|
An
|
|
.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.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
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
|
|
tells the number of transmit failures in the current update interval.
|
|
.Fa ra_nok
|
|
tells the number of transmit successes in the current update interval.
|
|
.Fa ra_pktrate
|
|
tells 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.
|
|
.Fa ra_last_raise
|
|
and
|
|
.Fa ra_raise_interval
|
|
are used to control the rate that RSS thresholds
|
|
.Dq decay .
|
|
.Fa ra_last_raise
|
|
tells when
|
|
.Fn ieee80211_rssadapt_raise_rate
|
|
was last called.
|
|
.Fa ra_raise_interval
|
|
tells 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
|
|
.Nx
|
|
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 wi 4
|
|
contains a reference implementation.
|
|
See
|
|
.Pa sys/dev/ic/wi.c .
|
|
.Sh SEE ALSO
|
|
.Xr wi 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 3.0 .
|
|
.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.
|