package/rt2x00/src/README

   1 ===============================================================================
   2  Installation and configuration instructions for the rt2x00 Modules
   3 ===============================================================================
   4
   5 ===============================================================================
   6  Table of contents:
   7 ========================
   8
   9  - 1: Minimal requirements
  10    - 1.1: kernel
  11    - 1.2: gcc
  12    - 1.3: make
  13  - 2: Hardware
  14    - 2.1: Chipsets
  15    - 2.2: RF button
  16  -  3: Module building & Installation
  17    - 3.1: Introduction
  18    - 3.2: Configure
  19    - 3.3: Build
  20    - 3.4: Installation
  21  - 4: Firmware
  22    - 4.1: Firmware files
  23    - 4.2: Firmware installation
  24    - 4.3: Firmware requirements
  25  - 5: Module loading
  26    - 5.1: Module load order
  27    - 5.2: Module load options
  28  - 6: Interfaces
  29    - 6.1: Wireless interfaces
  30    - 6.2: Input interface
  31  - 7: Interface configuration
  32    - 7.1: Minimal configuration
  33    - 7.2: Configuration tools
  34  - 8: Distribution specific notes
  35    - 8.1: Debian & derivatives
  36    - 8.2: Fedora
  37    - 8.3: Gentoo
  38    - 8.4: Mandriva
  39  - 9: Problems & Troubleshooting
  40    - 9.1: Debug information
  41    - 9.2: Debugfs
  42    - 9.3: Bug reporting
  43  - 10: Problems & Workarounds
  44    - 10.1: udev interface naming
  45    - 10.2: BUG - ifdown & ifup radio failure
  46  - 11: TODO list
  47  - 12: Contact us
  48
  49
  50 ===============================================================================
  51  1: Minimal requirements:
  52 =======================================
  53
  54 ===================
  55  1.1: kernel
  56 =========
  57
  58  - The minimal required kernel version is 2.6.22-rc1
  59
  60  - It is important that the installed kernel sources match
  61    the running kernel. Unless you are crosscompiling and you
  62    know what you are doing.
  63
  64  - Depending on what rt2x00 components will be built,
  65    some kernel configuration options are mandatory.
  66    It does however not matter if these options are compiled
  67    into the kernel or compiled as module.
  68
  69         Kernel config option    Required for component
  70         ------------------------------------------------------------------
  71         # CONFIG_NET_RADIO      all
  72         # CONFIG_MAC80211       all
  73         # CONFIG_WLAN_80211     all
  74         # CONFIG_PCI            rt2400pci, rt2500pci, rt61pci
  75         # CONFIG_USB            rt2500usb, rt73usb
  76         # CONFIG_HOTPLUG        rt61pci, rt73usb
  77         # CONFIG_FW_LOADER      rt61pci, rt73usb
  78         # CONFIG_CRC_ITU_T      rt61pci, rt73usb
  79         # CONFIG_DEBUG_FS       rt2x00 (optional, only for debug)
  80         # CONFIG_RFKILL         rt2400pci, rt2500pci, rt61pci (optional,
  81                                                         only for button support)
  82
  83 ===================
  84  1.2: GCC
  85 =========
  86
  87  - For building the rt2x00 components the same gcc version is required
  88    as was used to build your target kernel.
  89
  90 ===================
  91  1.3: make
  92 =========
  93
  94  - The program 'make' needs to be installed on the system. There are no
  95    further special requirements for this program.
  96
  97 ===============================================================================
  98  2: Hardware
  99 =======================================
 100
 101 ===================
 102  2.1: Chipsets
 103 =========
 104
 105  Support for each Ralink wireless chipset has been split into separate drivers.
 106
 107         # rt2400pci
 108                 - chipset: rt2400
 109                 - supports: rt2460
 110                 - bus type: PCI/PCMCIA/miniPCI
 111         # rt2500pci
 112                 - chipset: rt2500
 113                 - supports: rt2560
 114                 - bus type: PCI/PCMCIA/miniPCI
 115         # rt2500usb
 116                 - chipset: rt2570
 117                 - supports: rt2570
 118                 - bus type: USB
 119         # rt61pci
 120                 - chipset: rt61 (or rt2600)
 121                 - supports: rt2561, rt2561s, rt2661
 122                 - bus type: PCI/PCMCIA/miniPCI
 123         # rt73usb
 124                 - chipset: rt73
 125                 - supports: rt2571(w), rt2573, rt2671
 126                 - bus type: USB
 127
 128 ===================
 129  2.2: RF button
 130 =========
 131
 132  On some occasions the Ralink chipset has been built into a laptop.
 133  If that is the case, there usually is a hardware button that controls the
 134  radio of the wireless interface.
 135  If you have such a hardware device, make sure you enable hardware button
 136  support for your device in the configuration before building the rt2x00
 137  components.
 138  Note: This feature requires the enabling of the rfkill driver in the kernel.
 139
 140 ===============================================================================
 141  3: Module building & Installation
 142 =======================================
 143
 144 ===================
 145  3.1: Introduction
 146 =========
 147
 148  The following steps in this chapter concerning module building and
 149  installation need to be performed for each kernel. This means that
 150  after each kernel upgrade the modules need to be rebuild and
 151  reinstalled in order to make them work with the new kernel.
 152
 153 ===================
 154  3.2: Configure
 155 =========
 156
 157  Before starting to build the rt2x00 components it is recommended to look into
 158  the 'config' file first. In this file you can configure which components of
 159  rt2x00 should be built. And even more importantly, you can configure with
 160  what options the components will be built.
 161  To build all the rt2x00 drivers (with debug capabilities enabled) no changes
 162  in the configuration file are required. For most users this would be
 163  sufficient to start working with rt2x00.
 164
 165 ===================
 166  3.3: Build
 167 =========
 168
 169  To build all rt2x00 components which were enabled in the configuration file
 170  simply run (root privileges not required):
 171
 172         # $ make
 173
 174  All modules (.ko files) will be created in the current directory.
 175
 176 ===================
 177  3.4: Installation
 178 =========
 179
 180  All rt2x00 modules can be installed by doing (with root privileges):
 181
 182          # $ make install
 183
 184  With this command all rt2x00 modules (including rfkill and d80211) will be
 185  created in a newly created folder named 'rt2x00' inside the kernel modules
 186  directory (usually '/lib/modules/$(uname -r)/').
 187
 188
 189 ==============================================================================
 190  4: Firmware
 191 =======================================
 192
 193 ===================
 194  4.1: Firmware files
 195 =========
 196
 197  rt61pci and rt73usb require firmware to be available while loading the module.
 198  The following firmware files are available for each driver:
 199
 200         # rt61pci
 201                 - rt2561.bin
 202                 - rt2561s.bin
 203                 - rt2661.bin
 204
 205         # rt73usb
 206                 - rt73.bin
 207
 208 ===================
 209  4.2: Firmware installation
 210 =========
 211
 212  The latest firmware files are available in a separate .zip archive and can be
 213  downloaded from the support page on the Ralink website at
 214  http://www.ralinktech.com.
 215  Note that by a high level of logic, Ralink has named their firmware for rt73
 216  chipsets "rt71W" with a comment that it is for the rt2571W and rt2671 devices.
 217  For rt61pci 3 seperate firmware files are available, which one is used depends
 218  on which RT chip is on the device. Usually it is best to install all files.
 219  To install the firmware the firmware files need to be manually copied to the
 220  systems firmware folder (usually '/lib/firmware/') the exact folder depends
 221  on the distribution. When in doubt consult the distributions documentation.
 222
 223 ===================
 224  4.3: Firmware requirements
 225 =========
 226
 227  To load firmware when the module is loaded the hotplug daemon should be
 228  running. Make sure you either enable hotplugging manually before loading the
 229  module, or make sure hotplugging is enabled during the system boot process.
 230
 231
 232 ==============================================================================
 233  5: Module loading
 234 =======================================
 235
 236 ===================
 237  5.1: Module load order
 238 =========
 239
 240  When the modules have been properly installed by following the installation
 241  instructions from the previous section, the module handlers (i.e. modprobe)
 242  will automaticly resolve all module dependencies when loading the device
 243  specific driver.
 244
 245  When loading the modules manually with insmod, you should load them in the
 246  following order:
 247
 248         # eeprom_93cx6.ko (optional, only required for pci devices)
 249         # rt2x00lib.ko
 250         # rt2x00pci.ko (optional, only required for pci devices)
 251         # rt2x00usb.ko (optional, only required for usb devices)
 252         # rt2400pci.ko (optional, only required for rt2400 support)
 253         # rt2500pci.ko (optional, only required for rt2500 support)
 254         # rt2500usb.ko (optional, only required for rt2570 support)
 255         # rt61pci.ko (optional, only required for rt61 support)
 256         # rt73usb.ko (optional, only required for rt73 support)
 257
 258 ===================
 259  5.2: Module load options
 260 =========
 261
 262  None.
 263
 264
 265 ==============================================================================
 266  6: Interfaces
 267 =======================================
 268
 269 ===================
 270  6.1: Wireless interfaces
 271 =========
 272
 273  After loading the modules two interfaces will now be visible in ifconfig and
 274  iwconfig, namely wmaster0 and wlan0. The first device is the so called master
 275  device which is can be used by some userspace tools, but normally can be
 276  ignored by the user. The second interface wlan0 is the client interface which
 277  the user can configure.
 278  With rt2x00 it is possible to run multiple client interfaces with
 279  only a single device. 1 client interface can run in adhoc, managed or master
 280  mode while a second interface can run in monitor mode at the same time.
 281  More client interfaces can be added by issuing the following command
 282  (with root privileges):
 283
 284         # $ echo -n <name> > /sys/class/ieee80211/<dev>/add_iface
 285
 286  where the variable <name> is the name of the client interface that should be
 287  added (i.e. wlan1), and <dev> is the physical device where the new client
 288  interface should be attached to (i.e. phy0).
 289
 290 ===================
 291  6.2: Input interface
 292 =========
 293
 294  When the rfkill driver is being used a new input device with the name of the
 295  device specific module where the button belongs to will have been created.
 296  Whenever the user presses the hardware button the rfkill driver will
 297  automatically make sure the hardware radio is being disabled or enabled
 298  accordingly. When the user has opened the input device the radio will
 299  not be automatically controlled, but instead the input device will
 300  report all button events (KEY_RFKILL) to userspace where the user
 301  could have setup script to do all the work that has to be executed.
 302  This means that while the input device is opened, the user is responsible
 303  for the correct behaviour.
 304
 305
 306 ==============================================================================
 307  7: Interface configuration
 308 =======================================
 309
 310 ===================
 311  7.1: Minimal configuration
 312 =========
 313
 314  - After loading the modules the interface should be configured to start
 315    an association or work in monitor mode. The following steps are required
 316    for a minimal configuration to associate with a non-encrypted access point.
 317
 318  - Before bringing the client interface up, the working mode should be set:
 319
 320         # $ iwconfig wlan0 mode managed
 321
 322  - Configuration parts like essid and channel can be set before or after the
 323    client interface has been brought up.
 324
 325  - It is usually a good idea to set the essid:
 326
 327         # $ iwconfig wlan0 essid myessid
 328
 329  - In some situations the device also requires the channel to be manually set:
 330
 331         # $ iwconfig wlan0 channel mychannel
 332
 333  - To bring the client interface up:
 334
 335         # $ ifconfig wlan0 up
 336
 337  - After the client interface has been brought up, scanning can be performed
 338    to check if the desired AP is being detected.
 339
 340         # $ iwlist wlan0 scan
 341
 342  - To start an association attempt, the AP address should be set:
 343
 344         # $ iwconfig wlan0 ap mybssid
 345
 346 ===================
 347  7.2: Configuration tools
 348 =========
 349
 350  To configure the interface several tools are possible, the most basic tools
 351  are the wireless-tools that provide the iwconfig, iwpriv and iwlist commands.
 352  For WPA connections the wireless-tools are not sufficient, to configure the
 353  interface for WPA wireless network wpa_supplicant is required.
 354  For master mode functionality it is possible to only use the wireless-tools,
 355  but it is recommended to use hostapd instead. This tool offers the best
 356  functionality.
 357  For all configuration tools (wireless-tools, wpa_supplicant and hostapd) are
 358  manuals and howto's present in the manpages or on the internet. It is adviced
 359  to have at least read the manpages before using the tools for a better
 360  understanding on configuring the interface.
 361
 362
 363 ==============================================================================
 364  8: Distribution specific notes
 365 =======================================
 366
 367 ===================
 368  8.1: Debian & derivatives
 369 =========
 370
 371  In some instances installing the rt2x00 drivers on debian will result
 372  in the problem that the files are being copied into the wrong folder,
 373  which results in the fact that the driver cannot be loaded.
 374  Installing the drivers should be done manually in this case,
 375  please refer to the distributions documentation regarding the proper
 376  location of the kernel modules.
 377
 378 ===================
 379  8.2: Fedora
 380 =========
 381
 382  Although rt2x00 contains many backward compatibility fixes to ensure
 383  that all rt2x00 components will be able to compile and run on all
 384  systems that meet the minimal requirements, this does not work in all
 385  situations when the Fedora kernels are being used.
 386  The problem lies in the fact that Fedora (like most other distributions)
 387  heavily patch their kernel for better stability and more features.
 388  Unlike the other distributions however, Fedora does not pay attention to
 389  compatibility for external kernel drivers. This means that compiling rt2x00
 390  while using a Fedora kernel will result in compile errors regarding unknown
 391  fields in structures or problems with function arguments.
 392  For rt2x00 it is impossible to make all checks to support all Fedora kernel
 393  releases. This means that when rt2x00 compilation is failing while using a
 394  Fedora kernel we cannot give support for the compilation steps.
 395  We recommend the user to complain to the Fedora developers when this problem
 396  occurs.
 397  If the user has managed to compile rt2x00 for a Fedora kernel we will
 398  give support for possible problems while working with rt2x00. So the only
 399  part we do not support is the building of rt2x00.
 400  Please note that when you have edited the rt2x00 code to make it compile,
 401  it is advised to state those changes in bugreports while reporting other
 402  problems with rt2x00.
 403
 404 ===================
 405  8.3: Gentoo
 406 =========
 407
 408  rt2x00 can also be found in portage, both the beta releases and the cvs tree.
 409  Because rt2x00 is still experimental these ebuild are still masked, this means
 410  that before you can emerge them they first have to be unmasked.
 411  Gentoo provides various instructions on how this can be done on their website.
 412
 413 ===================
 414  8.4: Mandriva
 415 =========
 416
 417  In some instances installing the rt2x00 drivers on Mandriva will result
 418  in the problem that the files are being copied into the wrong folder,
 419  which results in the fact that the driver cannot be loaded.
 420  Installing the drivers should be done manually in this case,
 421  please refer to the distributions documentation regarding the proper
 422  location of the kernel modules.
 423
 424
 425 ==============================================================================
 426  9: Problems & Troubleshooting
 427 =======================================
 428
 429 ===================
 430  9.1: Debug information
 431 =========
 432
 433  When reporting problems make sure the driver has been compiled with debug
 434  enabled.
 435  If you have done so, the debug output can be found in the output
 436  of 'dmesg' and also in /var/log/messages and /var/log/syslog.
 437
 438 ===================
 439  9.2: Debugfs
 440 =========
 441
 442  rt2x00 provides several debugfs entries which can be used to help
 443  provide more information about the interface.
 444  To see the rt2x00 debugfs entries, debugfs should first be mounted,
 445  to do this you should issue the following command:
 446
 447          # $ mount -t debugfs none /debug
 448
 449  Where /debug is the directy on which the debugfs entries should appear,
 450  make sure this directory exists when mounting debugfs.
 451  With the debugfs folder, the rt2x00 folder with the rt2x00 debugfs entries
 452  will be created. Within the rt2x00 folder, each physical device will be
 453  represented by a folder named after the interface which belongs to this
 454  device. Within the folder the following files can be found:
 455
 456         # register
 457                 - This file contains the register contents of the interface.
 458         # eeprom
 459                 - This file contains the eeprom contents of the interface.
 460
 461 ===================
 462  9.3: Bug reporting
 463 =========
 464
 465  When reporting a bug or problem with the rt2x00 module,
 466  make sure you report the following information:
 467         # How to reproduce
 468         # RT2x00 debug output, usually found in /var/log/messages
 469         # Module version
 470         # Wireless card chipset, model and manufacturer
 471         # Kernel version (i.e. 2.6.17)
 472         # Hardware architecture (i.e. x86, AMD64, Sparc)
 473         # rt2x00 code changes done by the user
 474         # Anything else you may think will help us resolve the issue
 475
 476
 477 ==============================================================================
 478  10: Problems & Workarounds
 479 =======================================
 480
 481 ===================
 482  10.1: udev interface naming
 483 =========
 484
 485  In some cases when loading the rt2x00 drivers the interface names are
 486  different from the names used in this README. This is usually caused by the
 487  udev handler who has set some rules regarding the interface. These rules
 488  are usually set up by the distribution and have been created especially for
 489  for the legacy driver and their strange behavior.
 490  To change the rules udev applies to your interface you should edit the udev
 491  rules stored in /etc/udev/rules.d/ (exact location might be different
 492  depending on distribution).
 493  When editing this file, search for the line that contains something like this:
 494
 495         # ACTION=="add", SUBSYSTEM=="net", DRIVERS=="?*",
 496         #       SYSFS{address}=="<mac address>", NAME="<interface>"
 497         (line has been wrapped due to max line length limit)
 498
 499  Where <mac address> is the hardware address of your wireless networkcard,
 500  and <interface> is the interface name the interface takes as soon as the
 501  rt2x00 modules are loaded.
 502  This line should be changed to look like:
 503
 504         # ACTION=="add", SUBSYSTEM=="net", DRIVERS=="?*",
 505         #       SYSFS{address}=="<mac address>", SYSFS{type}=="801",
 506         #       NAME="wmaster0"
 507         # ACTION=="add", SUBSYSTEM=="net", DRIVERS=="?*",
 508         #       SYSFS{address}=="<mac address>", NAME="wlan0"
 509         (the 2 lines have been wrapped due to max line length limit)
 510
 511  Where <mac address> is the hardware address of your wireless networkcard,
 512  and thus should be the same as on the original line.
 513
 514 ===================
 515  10.2: BUG - ifdown & ifup radio failure
 516 =========
 517
 518  It is a known issue (and BUG) that the driver will fail to correctly resume
 519  its radio operations after the interface has been brought down and up again.
 520  It is still unknown what the cause for this issue could be, besides the fact
 521  that for some reason the device's registers have been incorrectly initialized.
 522  This issue also has impact on the device status after a suspend/resume
 523  operation. There is no known workaround for this yet.
 524
 525
 526 ==============================================================================
 527  11: TODO list
 528 =======================================
 529  See http://rt2x00.serialmonkey.com/wiki/index.php/Rt2x00_beta
 530
 531 ==============================================================================
 532  12: Contact us
 533 =======================================
 534
 535  - Website
 536         # http://rt2x00.serialmonkey.com/
 537         # http://rt2x00.serialmonkey.com/wiki/index.php/Rt2x00_beta
 538
 539  - Forums:
 540         # http://rt2x00.serialmonkey.com/phpBB2/
 541
 542  - Mailing list:
 543         # general: rt2400-general@lists.sourceforge.net
 544         # developers: rt2400-devel@lists.sourceforge.net
 545
 546  - Sourceforge:
 547         # http://sourceforge.net/projects/rt2400
 548