1.\" $NetBSD: ral.4,v 1.6 2008/11/20 09:06:44 wiz Exp $ 2.\" $OpenBSD: ral.4,v 1.53 2006/05/06 17:26:25 jmc Exp $ 3.\" 4.\" Copyright (c) 2005, 2006 5.\" Damien Bergamini <damien.bergamini@free.fr> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd June 7, 2006 20.Os 21.Dt RAL 4 22.Sh NAME 23.Nm ral 24.Nd Ralink Technology IEEE 802.11a/b/g wireless network driver 25.Sh SYNOPSIS 26.Cd "ral* at cardbus?" 27.Cd "ral* at pci?" 28.Cd "ral* at uhub? port ?" 29.Sh DESCRIPTION 30The 31.Nm 32driver supports PCI/CardBus wireless adapters based on the Ralink RT2500, 33RT2501, and RT2600 chipsets. 34The 35.Nm ral 36driver supports USB 2.0 wireless adapters based on the Ralink RT2500USB 37chipset. 38.Pp 39The RT2500 chipset is the first generation of 802.11b/g adapters from Ralink. 40It consists of two integrated chips, an RT2560 or RT2570(USB) MAC/BBP 41and an RT2525 or RT2526(USB) radio transceiver. 42.Pp 43The RT2501 chipset is the second generation of 802.11b/g adapters from Ralink. 44It consists of two integrated chips, an RT2561 MAC/BBP and an RT2527 radio 45transceiver. 46This chipset provides support for the IEEE 802.11e standard with multiple 47hardware transmission queues and allows scatter/gather for efficient DMA 48operations. 49.Pp 50The RT2600 chipset consists of two integrated chips, an RT2661 MAC/BBP and an 51RT2529 radio transceiver. 52This chipset uses the MIMO (multiple-input multiple-output) technology with 53multiple antennas to extend the operating range of the adapter and to achieve 54higher throughput. 55MIMO will be the basis of the future IEEE 802.11n standard. 56.Pp 57These are the modes the 58.Nm 59driver can operate in: 60.Bl -tag -width "IBSS-masterXX" 61.It BSS mode 62Also known as 63.Em infrastructure 64mode, this is used when associating with an access point, through 65which all traffic passes. 66This mode is the default. 67.It IBSS mode 68Also known as 69.Em IEEE ad-hoc 70mode or 71.Em peer-to-peer 72mode. 73This is the standardized method of operating without an access point. 74Stations associate with a service set. 75However, actual connections between stations are peer-to-peer. 76.It Host AP 77In this mode the driver acts as an access point (base station) 78for other cards. 79.It monitor mode 80In this mode the driver is able to receive packets without 81associating with an access point. 82This disables the internal receive filter and enables the card to 83capture packets from networks which it wouldn't normally have access to, 84or to scan for access points. 85.El 86.Pp 87.Nm 88supports software WEP. 89Wired Equivalent Privacy (WEP) is the de facto encryption standard 90for wireless networks. 91It can be typically configured in one of three modes: 92no encryption; 40-bit encryption; or 104-bit encryption. 93Unfortunately, due to serious weaknesses in WEP protocol 94it is strongly recommended that it not be used as the 95sole mechanism to secure wireless communication. 96WEP is not enabled by default. 97.Pp 98The transmit speed is user-selectable or can be adapted automatically by the 99driver depending on the received signal strength and on the number of hardware 100transmission retries. 101See 102.Xr rssadapt 9 103for more information. 104.Sh CONFIGURATION 105The 106.Nm 107driver can be configured at runtime with 108.Xr ifconfig 8 109or on boot with 110.Xr ifconfig.if 5 111using the following parameters: 112.Bl -tag -width Ds 113.It Cm bssid Ar bssid 114Set the desired BSSID. 115.It Fl bssid 116Unset the desired BSSID. 117The interface will automatically select a BSSID in this mode, which is 118the default. 119.It Cm chan Ar n 120Set the channel (radio frequency) to be used by the driver based on 121the given channel ID 122.Ar n . 123.It Fl chan 124Unset the desired channel to be used by the driver. 125The driver will automatically select a channel in this mode, which is 126the default. 127.It Cm media Ar media 128The 129.Nm 130driver supports the following 131.Ar media 132types: 133.Pp 134.Bl -tag -width autoselect -compact 135.It Cm autoselect 136Enable autoselection of the media type and options. 137.It Cm DS1 138Set 802.11b DS 1Mbps operation. 139.It Cm DS2 140Set 802.11b DS 2Mbps operation. 141.It Cm DS5 142Set 802.11b DS 5.5Mbps operation. 143.It Cm DS11 144Set 802.11b DS 11Mbps operation. 145.It Cm OFDM6 146Set 802.11a/g OFDM 6Mbps operation. 147.It Cm OFDM9 148Set 802.11a/g OFDM 9Mbps operation. 149.It Cm OFDM12 150Set 802.11a/g OFDM 12Mbps operation. 151.It Cm OFDM18 152Set 802.11a/g OFDM 18Mbps operation. 153.It Cm OFDM24 154Set 802.11a/g OFDM 24Mbps operation. 155.It Cm OFDM36 156Set 802.11a/g OFDM 36Mbps operation. 157.It Cm OFDM48 158Set 802.11a/g OFDM 48Mbps operation. 159.It Cm OFDM54 160Set 802.11a/g OFDM 54Mbps operation. 161.El 162.It Cm mediaopt Ar opts 163The 164.Nm 165driver supports the following media options: 166.Pp 167.Bl -tag -width monitor -compact 168.It Cm hostap 169Select Host AP operation. 170.It Cm ibss 171Select IBSS operation. 172.It Cm monitor 173Select monitor mode. 174.El 175.It Fl mediaopt Ar opts 176Disable the specified media options on the driver and return it to the 177default mode of operation (BSS). 178.It Cm mode Ar mode 179The 180.Nm 181driver supports the following modes: 182.Pp 183.Bl -tag -width 11b -compact 184.It Cm 11a 185Force 802.11a operation. 186.It Cm 11b 187Force 802.11b operation. 188.It Cm 11g 189Force 802.11g operation. 190.El 191.It Cm nwid Ar id 192Set the network ID. 193The 194.Ar id 195can either be any text string up to 32 characters in length, 196or a series of hexadecimal digits up to 64 digits. 197An empty 198.Ar id 199string allows the interface to connect to any available access points. 200By default the 201.Nm 202driver uses an empty string. 203Note that network ID is synonymous with Extended Service Set ID (ESSID). 204.It Cm nwkey Ar key 205Enable WEP encryption using the specified 206.Ar key . 207The 208.Ar key 209can either be a string, a series of hexadecimal digits (preceded by 210.Sq 0x ) , 211or a set of keys of the form 212.Dq n:k1,k2,k3,k4 , 213where 214.Sq n 215specifies which of the keys will be used for transmitted packets, 216and the four keys, 217.Dq k1 218through 219.Dq k4 , 220are configured as WEP keys. 221If a set of keys is specified, a comma 222.Pq Sq \&, 223within the key must be escaped with a backslash. 224Note that if multiple keys are used, their order must be the same within 225the network. 226.Nm 227is capable of using both 40-bit (5 characters or 10 hexadecimal digits) 228or 104-bit (13 characters or 26 hexadecimal digits) keys. 229.It Fl nwkey 230Disable WEP encryption. 231This is the default mode of operation. 232.El 233.Sh FILES 234The following firmware files are potentially loaded when an interface is 235brought up: 236.Pp 237.Bl -tag -width Ds -offset indent -compact 238.It /libdata/firmware/ral/ral-rt2561 239.It /libdata/firmware/ral/ral-rt2561s 240.It /libdata/firmware/ral/ral-rt2661 241.El 242.Pp 243RT2500 adapters do not require a firmware to operate. 244.Sh HARDWARE 245The following PCI adapters should work: 246.Bd -filled 247A-Link WL54H. 248Amigo AWI-926W. 249AMIT WL531P. 250AOpen AOI-831. 251ASUS WL-130g. 252ASUS WIFI-G-AAY. 253Atlantis Land A02-PCI-W54. 254Belkin F5D7000 v3. 255Canyon CN-WF511. 256CNet CWP-854. 257Compex WLP54G. 258Conceptronic C54Ri. 259Corega CG-WLPCI54GL. 260Digitus DN-7006G-RA. 261Dynalink WLG25PCI. 262E-Tech WGPI02. 263Edimax EW-7128g. 264Eminent EM3037. 265Encore ENLWI-G-RLAM. 266Eusso UGL2454-VPR. 267Fiberline WL-400P. 268Foxconn WLL-3350. 269Gigabyte GN-WPKG. 270Hawking HWP54GR. 271Hercules HWGPCI-54. 272iNexQ CR054g-009 (R03). 273JAHT WN-4054PCI. 274KCORP LifeStyle KLS-660. 275LevelOne WNC-0301 v2. 276Linksys WMP54G v4. 277Micronet SP906GK. 278Minitar MN54GPC-R. 279MSI MS-6834. 280MSI PC54G2. 281OvisLink EVO-W54PCI. 282PheeNet HWL-PCIG/RA. 283Pro-Nets PC80211G. 284Repotec RP-WP0854. 285SATech SN-54P. 286Signamax 065-1798. 287Sitecom WL-115. 288SparkLAN WL-660R. 289Surecom EP-9321-g. 290Sweex LC700030. 291TekComm NE-9321-g. 292Tonze PC-6200C. 293Unex CR054g-R02. 294Zinwell ZWX-G361. 295Zonet ZEW1600. 296.Ed 297.Pp 298The following CardBus adapters should work: 299.Bd -filled 300A-Link WL54PC. 301Alfa AWPC036. 302Amigo AWI-914W. 303AMIT WL531C. 304ASUS WL-107G. 305Atlantis Land A02-PCM-W54. 306Belkin F5D7010 v2. 307Canyon CN-WF513. 308CC\*[Am]C WL-2102. 309CNet CWC-854. 310Conceptronic C54RC. 311Corega CG-WLCB54GL. 312Digitus DN-7001G-RA. 313Dynalink WLG25CARDBUS. 314E-Tech WGPC02. 315E-Tech WGPC03. 316Edimax EW-7108PCg. 317Eminent EM3036. 318Encore ENPWI-G-RLAM. 319Eusso UGL2454-01R. 320Fiberline WL-400X. 321Gigabyte GN-WMKG. 322Hawking HWC54GR. 323Hercules HWGPCMCIA-54. 324JAHT WN-4054P(E). 325KCORP LifeStyle KLS-611. 326LevelOne WPC-0301 v2. 327Micronet SP908GK V3. 328Minitar MN54GCB-R. 329MSI CB54G2. 330MSI MS-6835. 331Pro-Nets CB80211G. 332Repotec RP-WB7108. 333SATech SN-54C. 334Sitecom WL-112. 335SparkLAN WL-611R. 336Surecom EP-9428-g. 337Sweex LC500050. 338TekComm NE-9428-g. 339Tonze PW-6200C. 340Unex MR054g-R02. 341Zinwell ZWX-G160. 342Zonet ZEW1500. 343.Ed 344.Pp 345The following Mini PCI adapters should work: 346.Bd -filled 347Amigo AWI-922W. 348Billionton MIWLGRL. 349Gigabyte GN-WIKG. 350MSI MP54G2. 351MSI MS-6833. 352Tonze PC-620C. 353Zinwell ZWX-G360. 354.Ed 355.Pp 356The following USB 2.0 adapters should work: 357.Bd -filled 358AMIT WL532U. 359ASUS WL-167g. 360Belkin F5D7050 v2000. 361Buffalo WLI-U2-KG54. 362Buffalo WLI-U2-KG54-AI. 363Buffalo WLI-U2-KG54-YB. 364CNet CWD-854. 365Compex WLU54G 2A1100. 366Conceptronic C54RU. 367D-Link DWL-G122 (b1). 368Dynalink WLG25USB. 369E-Tech WGUS02. 370Gigabyte GN-WBKG. 371Hercules HWGUSB2-54. 372KCORP LifeStyle KLS-685. 373Linksys HU200-TS. 374Linksys WUSB54G v4. 375Linksys WUSB54GP v4. 376MSI MS-6861. 377MSI MS-6865. 378MSI MS-6869. 379Nintendo Wi-Fi USB Connector. 380OvisLink Evo-W54USB. 381SerComm UB801R. 382SparkLAN WL-685R. 383Surecom EP-9001-g. 384Sweex LC100060. 385Tonze UW-6200C. 386Zinwell ZWX-G261. 387Zonet ZEW2500P. 388.Ed 389.Sh EXAMPLES 390The following 391.Xr ifconfig.if 5 392example creates a host-based access point on boot: 393.Bd -literal -offset indent 394inet 192.168.1.1 netmask 255.255.255.0 media autoselect \e 395 mediaopt hostap nwid my_net chan 11 396.Ed 397.Pp 398Configure ral0 for WEP, using hex key 399.Dq 0x1deadbeef1 : 400.Bd -literal -offset indent 401# ifconfig ral0 nwkey 0x1deadbeef1 402.Ed 403.Pp 404Return ral0 to its default settings: 405.Bd -literal -offset indent 406# ifconfig ral0 -bssid -chan media autoselect \e 407 nwid "" -nwkey 408.Ed 409.Pp 410Join an existing BSS network, 411.Dq my_net : 412.Bd -literal -offset indent 413# ifconfig ral0 192.168.1.1 netmask 0xffffff00 nwid my_net 414.Ed 415.Sh DIAGNOSTICS 416.Bl -diag 417.It "ral%d: could not read microcode %s" 418For some reason, the driver was unable to read the microcode file from the 419filesystem. 420The file might be missing or corrupted. 421.It "ral%d: could not load 8051 microcode" 422An error occurred while attempting to upload the microcode to the onboard 8051 423microcontroller unit. 424.It "ral%d: timeout waiting for MCU to initialize" 425The onboard 8051 microcontroller unit failed to initialize in time. 426.It "ral%d: device timeout" 427A frame dispatched to the hardware for transmission did not complete in time. 428The driver will reset the hardware. 429This should not happen. 430.El 431.Sh SEE ALSO 432.Xr arp 4 , 433.Xr cardbus 4 , 434.Xr ifmedia 4 , 435.Xr intro 4 , 436.Xr netintro 4 , 437.Xr pci 4 , 438.Xr usb 4 , 439.Xr ifconfig.if 5 , 440.Xr hostapd 8 , 441.Xr ifconfig 8 442.Pp 443Ralink Technology: 444.Pa http://www.ralinktech.com 445.Sh HISTORY 446The 447.Nm 448driver first appeared in 449.Ox 3.7 450and in 451.Nx 3.0 . 452Support for the RT2501 and RT2600 chipsets was added in 453.Ox 3.9 454and in 455.Nx 4.0 . 456.Sh AUTHORS 457The 458.Nm 459driver was written by 460.An Damien Bergamini Aq damien@openbsd.org . 461.Sh CAVEATS 462Some PCI 463.Nm 464adapters seem to strictly require a system supporting PCI 2.2 or greater and 465will likely not work in systems based on older revisions of the PCI 466specification. 467Check the board's PCI version before purchasing the card. 468.Pp 469The USB 470.Nm ral 471driver supports automatic control of the transmit speed in BSS mode only. 472Therefore the use of a USB 473.Nm ral 474adapter in Host AP mode is discouraged. 475