1.\" $NetBSD: rssadapt.9,v 1.3 2004/04/23 11:00:06 keihan 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 who 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.Fn ieee80211_rssadapt_choose 126.It Fa dvname 127The device driver uses 128.Fa dvname 129to indicate the name of the 130interface for the purpose of diagnostic and debug messages. 131The driver sets 132.Fa dvname 133to 134.Dv NULL 135when no messages are desired. 136.It Fa do_not_adapt 137If 138.Fa do_not_adapt 139is non-zero, then 140.Fn ieee80211_rssadapt_choose 141will choose the highest rate in 142.Fa rs 143that suits the destination, regardless of the RSS. 144.El 145The return value of 146.Fn ieee80211_rssadapt_choose 147is an index into 148.Fa rs , 149indicating its choice of transmit data rate. 150.It Fn ieee80211_rssadapt_input "ic" "ni" "ra" "rssi" 151The RSS serves as a rough estimate of the S/N at each node. 152A driver provides RSS updates using 153.Fn ieee80211_rssadapt_input , 154whose arguments are 155.Bl -tag -width "rssi" -compact 156.It Fa ic 157the wireless interface's 802.11 state object; 158.It Fa ni 159the 802.11 node whose RSS the driver is updating; 160.It Fa ra 161the node's 162.Nm 163state object; and 164.It Fa rssi 165the node's received signal strength indication. 166The range of 167.Fa rssi 168is from 0 to 255. 169.El 170.It Fn ieee80211_rssadapt_lower_rate "ic" "ni" "ra" "id" 171.It Fn ieee80211_rssadapt_raise_rate "ic" "ra" "id" 172Drivers call 173.Fn ieee80211_rssadapt_raise_rate 174and 175.Fn ieee80211_rssadapt_lower_rate 176to indicate transmit successes and failures, respectively. 177.Bl -tag -width "ni" -compact 178.It Fa ic 179is the 802.11 state object, 180.It Fa ni 181is the neighbor to whom the driver transmitted, 182.It Fa ra 183is the neighbor's 184.Nm 185state object, and 186.It Fa id 187tells statistics on the transmission attempt. 188.El 189.It Fn ieee80211_rssadapt_updatestats "ra" 190An 802.11 node is eligible for its RSS thresholds to decay every 1911/10 to 10 seconds. 192It is eligible more often (every 1/10 second) at high packet rates, 193and less often (every 10 seconds) at low packet rates. 194A driver assists 195.Nm 196in tracking the exponential-average packet rate by calling 197.Fn ieee80211_rssadapt_updatestats 198every 1/10th second for each node's 199.Vt ieee80211_rssadapt 200object. 201.Bl -tag -width "ra" -compact 202.It Fa ra 203the neighbor's 204.Nm 205state object. 206.El 207.El 208.Sh ALGORITHM 209.Nm 210monitors the RSS from neighboring 802.11 nodes, recording the 211exponential average RSS in each neighbor's 212.Vt ieee80211_rssadapt 213structure. 214.Nm 215uses transmit success/failure feedback from the 216device driver to fill a table of RSS thresholds. 217The table is indexed by packet size, 218.Va L , 219and a data rate, 220.Va R , 221to find out the minimum exponential-average RSS that a node must show before 222.Nm 223will indicate that a packet 224.Va L 225bytes long can be transmitted R bits per second with optimal expected 226throughput. 227When the driver indicates a unicast packet is transmitted unsuccessfully 228.Po 229that is, the NIC received no ACK for the packet 230.Pc , 231.Nm 232will move the corresponding RSS threshold toward the exponential 233average RSSI at the time of transmission. 234Thus several consecutive transmit failures for the same 235.Ao 236.Va L , 237.Va R 238.Ac 239tuple will ensure that the RSS threshold rises high enough that 240rate 241.Va R 242is abandoned for packets 243.Va L 244bytes long. 245When the driver indicates a successful transmission, 246the RSS threshold corresponding to the same packet length, but the 247next higher data rate, is lowered slightly. 248The RSS threshold is said to 249.Dq decay . 250This ensures that occasionally 251.Nm 252indicates the driver should try the next higher data rate, 253just in case conditions at the receiver have changed 254.Po 255for example, noise levels have fallen 256.Pc 257and a higher data rate can be supported at the same RSS level. 258.Pp 259The rate of decay is controlled. 260In an interval of 1/10th second 261to 10 seconds, only one RSS threshold per neighbor may decay. 262The interval is connected to the exponential-average rate that packets 263are being transmitted. 264At high packet rates, the interval is shortest. 265It is longest at low packet rates. 266The rationale for this is that RSS thresholds should not decay 267rapidly if there is no information from packet transmissions to 268counteract their decay. 269.Sh DATA STRUCTURES 270An 271.Vt ieee80211_rssdesc 272describes a transmission attempt. 273.Pp 274.Bd -literal -offset indent 275struct ieee80211_rssdesc { 276 u_int id_len; 277 u_int id_rateidx; 278 struct ieee80211_node *id_node; 279 u_int8_t id_rssi; 280}; 281.Ed 282.Pp 283.Fa id_len 284tells the length, in bytes, of the transmitted packet. 285.Fa id_node 286points at the neighbor's 287.Vt ieee8021_node , 288and 289.Fa id_rssi 290tells the exponential-average RSS at the time the packet was 291transmitted. 292.Fa id_rateidx 293is an index into the destination-neighbor's rate-set, 294.Fa id_node-\*[Gt]ni_rates , 295indicating the transmit data rate for the packet. 296.Pp 297An 298.Vt ieee80211_rssadapt 299contains the rate-adaptation state for a neighboring 802.11 node. 300Ordinarily a driver will 301.Dq subclass 302.Vt ieee80211_node . 303The 304.Vt ieee80211_rssadapt 305structure will be a subclass member. 306In this way, every node's 307.Nm 308condition is independently tracked and stored in its node object. 309.Pp 310.Bd -literal -offset indent 311struct ieee80211_rssadapt { 312 u_int16_t ra_avg_rssi; 313 u_int32_t ra_nfail; 314 u_int32_t ra_nok; 315 u_int32_t ra_pktrate; 316 u_int16_t ra_rate_thresh[IEEE80211_RSSADAPT_BKTS] 317 [IEEE80211_RATE_SIZE]; 318 struct timeval ra_last_raise; 319 struct timeval ra_raise_interval; 320}; 321.Ed 322.Pp 323.Fa ra_avg_rssi 324is the exponential-average RSS, shifted left 8 bits. 325.Fa ra_nfail 326tells the number of transmit failures in the current update interval. 327.Fa ra_nok 328tells the number of transmit successes in the current update interval. 329.Fa ra_pktrate 330tells the exponential average number of transmit failure/success 331indications over past update intervals. 332This approximates the rate of packet-transmission. 333.Fa ra_rate_thresh 334contains RSS thresholds that are indexed by 335.Aq "packet length, data rate" 336tuples. 337When this node's exponential-average RSS exceeds 338.Fa ra_rate_thresh[i][j] , 339then packets at most 128 x 8^i bytes long are eligible to be 340transmitted at the rate indexed by j. 341.Fa ra_last_raise 342and 343.Fa ra_raise_interval 344are used to control the rate that RSS thresholds 345.Dq decay . 346.Fa ra_last_raise 347tells when 348.Fn ieee80211_rssadapt_raise_rate 349was last called. 350.Fa ra_raise_interval 351tells the minimum period between consecutive calls to 352.Fn ieee80211_rssadapt_raise_rate . 353If 354.Fn ieee80211_rssadapt_raise_rate 355is called more than once in any period, the second and subsequent 356calls are ignored. 357.Sh CODE REFERENCES 358This section describes places within the 359.Nx 360source tree where actual code implementing or using 361.Nm 362can be found. 363All pathnames are relative to 364.Pa /usr/src . 365.Pp 366The code for 367.Nm 368is in the file 369.Pa sys/net80211/ieee80211_rssadapt.c . 370.Pp 371.Xr wi 4 372contains a reference implementation. 373See 374.Pa sys/dev/ic/wi.c . 375.Sh SEE ALSO 376.Xr wi 4 377.Rs 378.%A Javier del Prado Pavon 379.%A Sunghyun Choi 380.%T "Link Adaptation Strategy for IEEE 802.11 WLAN via Received Signal \ 381Strength Measurement" 382.%J "ICC'03" 383.%P pp. 1108-1113 384.%C Anchorage, Alaska 385.%D May 2003 386.Re 387.Sh HISTORY 388.Nm 389first appeared in 390.Nx 2.1 . 391.Sh AUTHORS 392.An David Young Aq dyoung@NetBSD.org 393.Sh BUGS 394To cope with interference from microwave ovens, frequency-hopping 395radios, and other sources of RF pulse-trains and bursts, 396.Nm 397should adapt the fragmentation threshold as well as the data rate. 398.Pp 399For improved throughput, 400.Nm 401should indicate to drivers when they should use the 802.11b 402short-preamble. 403.Pp 404The constants in 405.Fn ieee80211_rssadapt_updatestats 406should be configurable. 407