1.\" $NetBSD: rssadapt.9,v 1.5 2006/02/25 01:04:26 wiz Exp $ 2.\" 3.\" Copyright (c) 2004 David Young. All rights reserved. 4.\" 5.\" This code is by David Young. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above 13.\" copyright notice, this list of conditions and the following 14.\" disclaimer in the documentation and/or other materials 15.\" provided with the distribution. 16.\" 3. The name of David Young may not be used to endorse or promote 17.\" products derived from this software without specific prior 18.\" written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY David Young ``AS IS'' AND ANY 21.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 23.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL David 24.\" Young BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 26.\" TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 28.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31.\" POSSIBILITY OF SUCH DAMAGE. 32.\" 33.Dd March 23, 2004 34.Dt RSSADAPT 9 35.Os 36.Sh NAME 37.Nm rssadapt , 38.Nm ieee80211_rssadapt_choose , 39.Nm ieee80211_rssadapt_input , 40.Nm ieee80211_rssadapt_lower_rate , 41.Nm ieee80211_rssadapt_raise_rate , 42.Nm ieee80211_rssadapt_updatestats 43.Nd rate adaptation based on received signal strength 44.Sh SYNOPSIS 45.In net80211/ieee80211_var.h 46.In net80211/ieee80211_rssadapt.h 47.Ft void 48.Fn ieee80211_rssadapt_input "struct ieee80211com *ic" \ 49"struct ieee80211_node *ni" "struct ieee80211_rssadapt *ra" "int rssi" 50.Ft void 51.Fn ieee80211_rssadapt_lower_rate "struct ieee80211com *ic" \ 52"struct ieee80211_node *ni" "struct ieee80211_rssadapt *ra" \ 53"struct ieee80211_rssdesc *id" 54.Ft void 55.Fn ieee80211_rssadapt_raise_rate "struct ieee80211com *ic" \ 56"struct ieee80211_rssadapt *ra" "struct ieee80211_rssdesc *id" 57.Ft void 58.Fn ieee80211_rssadapt_updatestats "struct ieee80211_rssadapt *ra" 59.Ft int 60.Fn ieee80211_rssadapt_choose "struct ieee80211_rssadapt *ra" \ 61"struct ieee80211_rateset *rs" "struct ieee80211_frame *wh" "u_int len" \ 62"int fixed_rate" "const char *dvname" "int do_not_adapt" 63.Sh DESCRIPTION 64The 65.Nm 66module provides rapid adaptation of transmission data rate to 802.11 67device drivers based on received-signal strength 68.Pq RSS . 69A driver needs only to provide 70.Nm 71with indications of RSS and failure/success of transmissions for 72each 802.11 client or peer. 73For each transmit packet, 74.Nm 75chooses the transmission data rate that offers the best expected 76throughput, given the packet's length and destination. 77.Pp 78.Nm 79models an 802.11 channel very simply 80.Po 81see also the 82.Sx BUGS 83section 84.Pc . 85It assumes that the packet-error rate 86.Pq PER 87is determined by the signal-to-noise ratio 88.Pq S/N 89at the receiver, the transmission data rate, and the packet length. 90The S/N determines the choice of data rate that yields the lowest 91PER for all packets of a certain length. 92.Sh FUNCTIONS 93.Bl -tag -width 18n -compact 94.It Fn ieee80211_rssadapt_choose "ra" "rs" "wh" "len" "fixed_rate" "dvname" \ 95"do_not_adapt" 96Choose the transmission data rate for a packet. 97.Bl -tag -width "do_not_adapt" -compact 98.It Fa ra 99Ordinarily, the 100.Nm 101state object belonging to the node which is the packet destination. 102However, if the destination is a broadcast/multicast address, then 103.Fa ra 104belongs to the BSS node, 105.Va ic-\*[Gt]ic_bss . 106.It Fa rs 107A list of eligible data rates for the node; for example, the 108rates negotiated when the node associated with the network. 109.It Fa len 110The packet length in bytes, including the 802.11 header and 111frame check sequence 112.Pq FCS . 113.It Fa fixed_rate 114If the operator has set the data rate using, for example, 115.Ic "ifconfig wi0 media ds1" , 116then 117.Fa fixed_rate 118tells the index of that rate in 119.Fa rs . 120.Nm 121obeys a fixed data rate whenever the 802.11 standard allows it: 122sometimes the standard requires multicast/broadcast packets to be 123transmitted at a so-called 124.Dq basic rate . 125.It Fa dvname 126The device driver uses 127.Fa dvname 128to indicate the name of the 129interface for the purpose of diagnostic and debug messages. 130The driver sets 131.Fa dvname 132to 133.Dv NULL 134when no messages are desired. 135.It Fa do_not_adapt 136If 137.Fa do_not_adapt 138is non-zero, then 139.Fn ieee80211_rssadapt_choose 140will choose the highest rate in 141.Fa rs 142that suits the destination, regardless of the RSS. 143.El 144The return value of 145.Fn ieee80211_rssadapt_choose 146is an index into 147.Fa rs , 148indicating its choice of transmit data rate. 149.It Fn ieee80211_rssadapt_input "ic" "ni" "ra" "rssi" 150The RSS serves as a rough estimate of the S/N at each node. 151A driver provides RSS updates using 152.Fn ieee80211_rssadapt_input , 153whose arguments are: 154.Bl -tag -width "rssi" -compact 155.It Fa ic 156The wireless interface's 802.11 state object. 157.It Fa ni 158The 802.11 node whose RSS the driver is updating. 159.It Fa ra 160The node's 161.Nm 162state object. 163.It Fa rssi 164The node's received signal strength indication. 165The range of 166.Fa rssi 167is from 0 to 255. 168.El 169.It Fn ieee80211_rssadapt_lower_rate "ic" "ni" "ra" "id" 170.It Fn ieee80211_rssadapt_raise_rate "ic" "ra" "id" 171Drivers call 172.Fn ieee80211_rssadapt_raise_rate 173and 174.Fn ieee80211_rssadapt_lower_rate 175to indicate transmit successes and failures, respectively. 176.Bl -tag -width "ni" -compact 177.It Fa ic 178The 802.11 state object. 179.It Fa ni 180The neighbor to whom the driver transmitted. 181.It Fa ra 182The neighbor's 183.Nm 184state object. 185.It Fa id 186DIsplays statistics on the transmission attempt. 187.El 188.It Fn ieee80211_rssadapt_updatestats "ra" 189An 802.11 node is eligible for its RSS thresholds to decay every 1901/10 to 10 seconds. 191It is eligible more often (every 1/10 second) at high packet rates, 192and less often (every 10 seconds) at low packet rates. 193A driver assists 194.Nm 195in tracking the exponential-average packet rate by calling 196.Fn ieee80211_rssadapt_updatestats 197every 1/10th second for each node's 198.Vt ieee80211_rssadapt 199object. 200.Bl -tag -width "ra" -compact 201.It Fa ra 202The neighbor's 203.Nm 204state object. 205.El 206.El 207.Sh ALGORITHM 208.Nm 209monitors the RSS from neighboring 802.11 nodes, recording the 210exponential average RSS in each neighbor's 211.Vt ieee80211_rssadapt 212structure. 213.Nm 214uses transmit success/failure feedback from the 215device driver to fill a table of RSS thresholds. 216The table is indexed by packet size, 217.Va L , 218and a data rate, 219.Va R , 220to find out the minimum exponential-average RSS that a node must show before 221.Nm 222will indicate that a packet 223.Va L 224bytes long can be transmitted R bits per second with optimal expected 225throughput. 226When the driver indicates a unicast packet is transmitted unsuccessfully 227.Po 228that is, the NIC received no ACK for the packet 229.Pc , 230.Nm 231will move the corresponding RSS threshold toward the exponential 232average RSSI at the time of transmission. 233Thus several consecutive transmit failures for the same 234.Ao 235.Va L , 236.Va R 237.Ac 238tuple will ensure that the RSS threshold rises high enough that 239rate 240.Va R 241is abandoned for packets 242.Va L 243bytes long. 244When the driver indicates a successful transmission, 245the RSS threshold corresponding to the same packet length, but the 246next higher data rate, is lowered slightly. 247The RSS threshold is said to 248.Dq decay . 249This ensures that occasionally 250.Nm 251indicates the driver should try the next higher data rate, 252just in case conditions at the receiver have changed 253.Po 254for example, noise levels have fallen 255.Pc 256and a higher data rate can be supported at the same RSS level. 257.Pp 258The rate of decay is controlled. 259In an interval of 1/10th second 260to 10 seconds, only one RSS threshold per neighbor may decay. 261The interval is connected to the exponential-average rate that packets 262are being transmitted. 263At high packet rates, the interval is shortest. 264It is longest at low packet rates. 265The rationale for this is that RSS thresholds should not decay 266rapidly if there is no information from packet transmissions to 267counteract their decay. 268.Sh DATA STRUCTURES 269An 270.Vt ieee80211_rssdesc 271describes a transmission attempt. 272.Pp 273.Bd -literal -offset indent 274struct ieee80211_rssdesc { 275 u_int id_len; 276 u_int id_rateidx; 277 struct ieee80211_node *id_node; 278 u_int8_t id_rssi; 279}; 280.Ed 281.Pp 282.Fa id_len 283is the length, in bytes, of the transmitted packet. 284.Fa id_node 285points to the neighbor's 286.Vt ieee8021_node , 287and 288.Fa id_rssi 289is the exponential-average RSS at the time the packet was 290transmitted. 291.Fa id_rateidx 292is an index into the destination-neighbor's rate-set, 293.Fa id_node-\*[Gt]ni_rates , 294indicating the transmit data rate for the packet. 295.Pp 296An 297.Vt ieee80211_rssadapt 298contains the rate-adaptation state for a neighboring 802.11 node. 299Ordinarily a driver will 300.Dq subclass 301.Vt ieee80211_node . 302The 303.Vt ieee80211_rssadapt 304structure will be a subclass member. 305In this way, every node's 306.Nm 307condition is independently tracked and stored in its node object. 308.Pp 309.Bd -literal -offset indent 310struct ieee80211_rssadapt { 311 u_int16_t ra_avg_rssi; 312 u_int32_t ra_nfail; 313 u_int32_t ra_nok; 314 u_int32_t ra_pktrate; 315 u_int16_t ra_rate_thresh[IEEE80211_RSSADAPT_BKTS] 316 [IEEE80211_RATE_SIZE]; 317 struct timeval ra_last_raise; 318 struct timeval ra_raise_interval; 319}; 320.Ed 321.Pp 322.Fa ra_avg_rssi 323is the exponential-average RSS, shifted left 8 bits. 324.Fa ra_nfail 325tells the number of transmit failures in the current update interval. 326.Fa ra_nok 327tells the number of transmit successes in the current update interval. 328.Fa ra_pktrate 329tells the exponential average number of transmit failure/success 330indications over past update intervals. 331This approximates the rate of packet-transmission. 332.Fa ra_rate_thresh 333contains RSS thresholds that are indexed by 334.Aq "packet length, data rate" 335tuples. 336When this node's exponential-average RSS exceeds 337.Fa ra_rate_thresh[i][j] , 338then packets at most 128 x 8^i bytes long are eligible to be 339transmitted at the rate indexed by j. 340.Fa ra_last_raise 341and 342.Fa ra_raise_interval 343are used to control the rate that RSS thresholds 344.Dq decay . 345.Fa ra_last_raise 346indicates when 347.Fn ieee80211_rssadapt_raise_rate 348was last called. 349.Fa ra_raise_interval 350tells the minimum period between consecutive calls to 351.Fn ieee80211_rssadapt_raise_rate . 352If 353.Fn ieee80211_rssadapt_raise_rate 354is called more than once in any period, the second and subsequent 355calls are ignored. 356.Sh CODE REFERENCES 357This section describes places within the 358.Nx 359source tree where actual code implementing or using 360.Nm 361can be found. 362All pathnames are relative to 363.Pa /usr/src . 364.Pp 365The code for 366.Nm 367is in the file 368.Pa sys/net80211/ieee80211_rssadapt.c . 369.Pp 370.Xr wi 4 371contains a reference implementation. 372See 373.Pa sys/dev/ic/wi.c . 374.Sh SEE ALSO 375.Xr wi 4 376.Rs 377.%A Javier del Prado Pavon 378.%A Sunghyun Choi 379.%T "Link Adaptation Strategy for IEEE 802.11 WLAN via Received Signal \ 380Strength Measurement" 381.%J "ICC'03" 382.%P pp. 1108-1113 383.%C Anchorage, Alaska 384.%D May 2003 385.Re 386.Sh HISTORY 387.Nm 388first appeared in 389.Nx 3.0 . 390.Sh AUTHORS 391.An David Young Aq dyoung@NetBSD.org 392.Sh BUGS 393To cope with interference from microwave ovens, frequency-hopping 394radios, and other sources of RF pulse-trains and bursts, 395.Nm 396should adapt the fragmentation threshold as well as the data rate. 397.Pp 398For improved throughput, 399.Nm 400should indicate to drivers when they should use the 802.11b 401short-preamble. 402.Pp 403The constants in 404.Fn ieee80211_rssadapt_updatestats 405should be configurable. 406