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