From 061f5fc4ee5c692bccd6264a2c4165555eb81db9 Mon Sep 17 00:00:00 2001 From: dyoung Date: Mon, 29 Mar 2004 04:14:03 +0000 Subject: [PATCH] Add a manual page to section 9 for rssadapt, the rate-adaptation framework. --- distrib/sets/lists/comp/mi | 14 +- share/man/man9/Makefile | 10 +- share/man/man9/rssadapt.9 | 407 +++++++++++++++++++++++++++++++++++++ 3 files changed, 428 insertions(+), 3 deletions(-) create mode 100644 share/man/man9/rssadapt.9 diff --git a/distrib/sets/lists/comp/mi b/distrib/sets/lists/comp/mi index c3dc8eef55ba..a080da1a5ebe 100644 --- a/distrib/sets/lists/comp/mi +++ b/distrib/sets/lists/comp/mi @@ -1,4 +1,4 @@ -# $NetBSD: mi,v 1.689 2004/03/28 18:23:27 he Exp $ +# $NetBSD: mi,v 1.690 2004/03/29 04:14:03 dyoung Exp $ ./etc/mtree/set.comp comp-sys-root ./usr/bin/addr2line comp-debug-bin bfd ./usr/bin/ar comp-util-bin bfd @@ -4910,6 +4910,11 @@ ./usr/share/man/cat9/hz.0 comp-sys-catman .cat ./usr/share/man/cat9/i386/bios32_service.0 comp-sys-catman .cat ./usr/share/man/cat9/i386/bioscall.0 comp-sys-catman .cat +./usr/share/man/cat9/ieee80211_rssadapt_choose.0 comp-sys-catman .cat +./usr/share/man/cat9/ieee80211_rssadapt_input.0 comp-sys-catman .cat +./usr/share/man/cat9/ieee80211_rssadapt_lower_rate.0 comp-sys-catman .cat +./usr/share/man/cat9/ieee80211_rssadapt_raise_rate.0 comp-sys-catman .cat +./usr/share/man/cat9/ieee80211_rssadapt_updatestats.0 comp-sys-catman .cat ./usr/share/man/cat9/in4_cksum.0 comp-sys-catman .cat ./usr/share/man/cat9/in6_cksum.0 comp-sys-catman .cat ./usr/share/man/cat9/in_cksum.0 comp-sys-catman .cat @@ -5172,6 +5177,7 @@ ./usr/share/man/cat9/rnd_add_uint32.0 comp-sys-catman .cat ./usr/share/man/cat9/rnd_attach_source.0 comp-sys-catman .cat ./usr/share/man/cat9/rnd_detach_source.0 comp-sys-catman .cat +./usr/share/man/cat9/rssadapt.0 comp-sys-catman .cat ./usr/share/man/cat9/rt_timer.0 comp-sys-catman .cat ./usr/share/man/cat9/rt_timer_add.0 comp-sys-catman .cat ./usr/share/man/cat9/rt_timer_queue_change.0 comp-sys-catman .cat @@ -8555,6 +8561,11 @@ ./usr/share/man/man9/hz.9 comp-sys-man .man ./usr/share/man/man9/i386/bios32_service.9 comp-sys-man .man ./usr/share/man/man9/i386/bioscall.9 comp-sys-man .man +./usr/share/man/man9/ieee80211_rssadapt_choose.9 comp-sys-man .man +./usr/share/man/man9/ieee80211_rssadapt_input.9 comp-sys-man .man +./usr/share/man/man9/ieee80211_rssadapt_lower_rate.9 comp-sys-man .man +./usr/share/man/man9/ieee80211_rssadapt_raise_rate.9 comp-sys-man .man +./usr/share/man/man9/ieee80211_rssadapt_updatestats.9 comp-sys-man .man ./usr/share/man/man9/in4_cksum.9 comp-sys-man .man ./usr/share/man/man9/in6_cksum.9 comp-sys-man .man ./usr/share/man/man9/in_cksum.9 comp-sys-man .man @@ -8817,6 +8828,7 @@ ./usr/share/man/man9/rnd_add_uint32.9 comp-sys-man .man ./usr/share/man/man9/rnd_attach_source.9 comp-sys-man .man ./usr/share/man/man9/rnd_detach_source.9 comp-sys-man .man +./usr/share/man/man9/rssadapt.9 comp-sys-man .man ./usr/share/man/man9/rt_timer.9 comp-sys-man .man ./usr/share/man/man9/rt_timer_add.9 comp-sys-man .man ./usr/share/man/man9/rt_timer_queue_change.9 comp-sys-man .man diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 5bc761ee2675..9e4f95520f65 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.160 2004/03/24 19:37:10 atatat Exp $ +# $NetBSD: Makefile,v 1.161 2004/03/29 04:14:04 dyoung Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -27,7 +27,8 @@ MAN= altq.9 arc4random.9 arp.9 audio.9 autoconf.9 \ pcmcia.9 pfil.9 physio.9 pmap.9 pmatch.9 pmc.9 \ pool.9 pool_cache.9 powerhook_establish.9 ppsratecheck.9 \ properties.9 preempt.9 \ - radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rt_timer.9 \ + radio.9 ras.9 rasops.9 ratecheck.9 resettodr.9 rnd.9 rssadapt.9 \ + rt_timer.9 \ SCHED_LOCK.9 scheduler.9 \ scsipi.9 setjmp.9 setrunqueue.9 shutdownhook_establish.9 \ signal.9 softintr.9 spl.9 store.9 suser.9 suspendsched.9 \ @@ -408,6 +409,11 @@ MLINKS+=rasops.9 rasops_init.9 \ rasops.9 rasops_reconfig.9 MLINKS+=rnd.9 rnd_attach_source.9 rnd.9 rnd_detach_source.9 \ rnd.9 rnd_add_data.9 rnd.9 rnd_add_uint32.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+=rt_timer.9 rt_timer_queue_create.9 rt_timer.9 rt_timer_queue_change.9 \ rt_timer.9 rt_timer_queue_destroy.9 rt_timer.9 rt_timer_add.9 \ rt_timer.9 rt_timer_remove_all.9 diff --git a/share/man/man9/rssadapt.9 b/share/man/man9/rssadapt.9 new file mode 100644 index 000000000000..8ef3d5745103 --- /dev/null +++ b/share/man/man9/rssadapt.9 @@ -0,0 +1,407 @@ +.\" $NetBSD: rssadapt.9,v 1.1 2004/03/29 04:14:04 dyoung 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 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 2.1 . +.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.