share/man/man4/ral.4

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