===============================================================================
Installation and configuration instructions for the rt2x00 Modules
===============================================================================
===============================================================================
Table of contents:
========================
- 1: Minimal requirements
- 1.1: kernel
- 1.2: gcc
- 1.3: make
- 2: Hardware
- 2.1: Chipsets
- 2.2: RF button
- 3: Module building & Installation
- 3.1: Introduction
- 3.2: Configure
- 3.3: Build
- 3.4: Installation
- 4: Firmware
- 4.1: Firmware files
- 4.2: Firmware installation
- 4.3: Firmware requirements
- 5: Module loading
- 5.1: Module load order
- 5.2: Module load options
- 6: Interfaces
- 6.1: Wireless interfaces
- 6.2: Input interface
- 7: Interface configuration
- 7.1: Minimal configuration
- 7.2: Configuration tools
- 8: Distribution specific notes
- 8.1: Debian & derivatives
- 8.2: Fedora
- 8.3: Gentoo
- 8.4: Mandriva
- 9: Problems & Troubleshooting
- 9.1: Debug information
- 9.2: Debugfs
- 9.3: Bug reporting
- 10: Problems & Workarounds
- 10.1: udev interface naming
- 10.2: BUG - ifdown & ifup radio failure
- 11: TODO list
- 12: Contact us
===============================================================================
1: Minimal requirements:
=======================================
===================
1.1: kernel
=========
- The minimal required kernel version is 2.6.22-rc1
- It is important that the installed kernel sources match
the running kernel. Unless you are crosscompiling and you
know what you are doing.
- Depending on what rt2x00 components will be built,
some kernel configuration options are mandatory.
It does however not matter if these options are compiled
into the kernel or compiled as module.
Kernel config option Required for component
------------------------------------------------------------------
# CONFIG_NET_RADIO all
# CONFIG_MAC80211 all
# CONFIG_WLAN_80211 all
# CONFIG_PCI rt2400pci, rt2500pci, rt61pci
# CONFIG_USB rt2500usb, rt73usb
# CONFIG_HOTPLUG rt61pci, rt73usb
# CONFIG_FW_LOADER rt61pci, rt73usb
# CONFIG_CRC_ITU_T rt61pci, rt73usb
# CONFIG_DEBUG_FS rt2x00 (optional, only for debug)
# CONFIG_RFKILL rt2400pci, rt2500pci, rt61pci (optional,
only for button support)
===================
1.2: GCC
=========
- For building the rt2x00 components the same gcc version is required
as was used to build your target kernel.
===================
1.3: make
=========
- The program 'make' needs to be installed on the system. There are no
further special requirements for this program.
===============================================================================
2: Hardware
=======================================
===================
2.1: Chipsets
=========
Support for each Ralink wireless chipset has been split into separate drivers.
# rt2400pci
- chipset: rt2400
- supports: rt2460
- bus type: PCI/PCMCIA/miniPCI
# rt2500pci
- chipset: rt2500
- supports: rt2560
- bus type: PCI/PCMCIA/miniPCI
# rt2500usb
- chipset: rt2570
- supports: rt2570
- bus type: USB
# rt61pci
- chipset: rt61 (or rt2600)
- supports: rt2561, rt2561s, rt2661
- bus type: PCI/PCMCIA/miniPCI
# rt73usb
- chipset: rt73
- supports: rt2571(w), rt2573, rt2671
- bus type: USB
===================
2.2: RF button
=========
On some occasions the Ralink chipset has been built into a laptop.
If that is the case, there usually is a hardware button that controls the
radio of the wireless interface.
If you have such a hardware device, make sure you enable hardware button
support for your device in the configuration before building the rt2x00
components.
Note: This feature requires the enabling of the rfkill driver in the kernel.
===============================================================================
3: Module building & Installation
=======================================
===================
3.1: Introduction
=========
The following steps in this chapter concerning module building and
installation need to be performed for each kernel. This means that
after each kernel upgrade the modules need to be rebuild and
reinstalled in order to make them work with the new kernel.
===================
3.2: Configure
=========
Before starting to build the rt2x00 components it is recommended to look into
the 'config' file first. In this file you can configure which components of
rt2x00 should be built. And even more importantly, you can configure with
what options the components will be built.
To build all the rt2x00 drivers (with debug capabilities enabled) no changes
in the configuration file are required. For most users this would be
sufficient to start working with rt2x00.
===================
3.3: Build
=========
To build all rt2x00 components which were enabled in the configuration file
simply run (root privileges not required):
# $ make
All modules (.ko files) will be created in the current directory.
===================
3.4: Installation
=========
All rt2x00 modules can be installed by doing (with root privileges):
# $ make install
With this command all rt2x00 modules (including rfkill and d80211) will be
created in a newly created folder named 'rt2x00' inside the kernel modules
directory (usually '/lib/modules/$(uname -r)/').
==============================================================================
4: Firmware
=======================================
===================
4.1: Firmware files
=========
rt61pci and rt73usb require firmware to be available while loading the module.
The following firmware files are available for each driver:
# rt61pci
- rt2561.bin
- rt2561s.bin
- rt2661.bin
# rt73usb
- rt73.bin
===================
4.2: Firmware installation
=========
The latest firmware files are available in a separate .zip archive and can be
downloaded from the support page on the Ralink website at
http://www.ralinktech.com.
Note that by a high level of logic, Ralink has named their firmware for rt73
chipsets "rt71W" with a comment that it is for the rt2571W and rt2671 devices.
For rt61pci 3 seperate firmware files are available, which one is used depends
on which RT chip is on the device. Usually it is best to install all files.
To install the firmware the firmware files need to be manually copied to the
systems firmware folder (usually '/lib/firmware/') the exact folder depends
on the distribution. When in doubt consult the distributions documentation.
===================
4.3: Firmware requirements
=========
To load firmware when the module is loaded the hotplug daemon should be
running. Make sure you either enable hotplugging manually before loading the
module, or make sure hotplugging is enabled during the system boot process.
==============================================================================
5: Module loading
=======================================
===================
5.1: Module load order
=========
When the modules have been properly installed by following the installation
instructions from the previous section, the module handlers (i.e. modprobe)
will automaticly resolve all module dependencies when loading the device
specific driver.
When loading the modules manually with insmod, you should load them in the
following order:
# eeprom_93cx6.ko (optional, only required for pci devices)
# rt2x00lib.ko
# rt2x00pci.ko (optional, only required for pci devices)
# rt2x00usb.ko (optional, only required for usb devices)
# rt2400pci.ko (optional, only required for rt2400 support)
# rt2500pci.ko (optional, only required for rt2500 support)
# rt2500usb.ko (optional, only required for rt2570 support)
# rt61pci.ko (optional, only required for rt61 support)
# rt73usb.ko (optional, only required for rt73 support)
===================
5.2: Module load options
=========
None.
==============================================================================
6: Interfaces
=======================================
===================
6.1: Wireless interfaces
=========
After loading the modules two interfaces will now be visible in ifconfig and
iwconfig, namely wmaster0 and wlan0. The first device is the so called master
device which is can be used by some userspace tools, but normally can be
ignored by the user. The second interface wlan0 is the client interface which
the user can configure.
With rt2x00 it is possible to run multiple client interfaces with
only a single device. 1 client interface can run in adhoc, managed or master
mode while a second interface can run in monitor mode at the same time.
More client interfaces can be added by issuing the following command
(with root privileges):
# $ echo -n <name> > /sys/class/ieee80211/<dev>/add_iface
where the variable <name> is the name of the client interface that should be
added (i.e. wlan1), and <dev> is the physical device where the new client
interface should be attached to (i.e. phy0).
===================
6.2: Input interface
=========
When the rfkill driver is being used a new input device with the name of the
device specific module where the button belongs to will have been created.
Whenever the user presses the hardware button the rfkill driver will
automatically make sure the hardware radio is being disabled or enabled
accordingly. When the user has opened the input device the radio will
not be automatically controlled, but instead the input device will
report all button events (KEY_RFKILL) to userspace where the user
could have setup script to do all the work that has to be executed.
This means that while the input device is opened, the user is responsible
for the correct behaviour.
==============================================================================
7: Interface configuration
=======================================
===================
7.1: Minimal configuration
=========
- After loading the modules the interface should be configured to start
an association or work in monitor mode. The following steps are required
for a minimal configuration to associate with a non-encrypted access point.
- Before bringing the client interface up, the working mode should be set:
# $ iwconfig wlan0 mode managed
- Configuration parts like essid and channel can be set before or after the
client interface has been brought up.
- It is usually a good idea to set the essid:
# $ iwconfig wlan0 essid myessid
- In some situations the device also requires the channel to be manually set:
# $ iwconfig wlan0 channel mychannel
- To bring the client interface up:
# $ ifconfig wlan0 up
- After the client interface has been brought up, scanning can be performed
to check if the desired AP is being detected.
# $ iwlist wlan0 scan
- To start an association attempt, the AP address should be set:
# $ iwconfig wlan0 ap mybssid
===================
7.2: Configuration tools
=========
To configure the interface several tools are possible, the most basic tools
are the wireless-tools that provide the iwconfig, iwpriv and iwlist commands.
For WPA connections the wireless-tools are not sufficient, to configure the
interface for WPA wireless network wpa_supplicant is required.
For master mode functionality it is possible to only use the wireless-tools,
but it is recommended to use hostapd instead. This tool offers the best
functionality.
For all configuration tools (wireless-tools, wpa_supplicant and hostapd) are
manuals and howto's present in the manpages or on the internet. It is adviced
to have at least read the manpages before using the tools for a better
understanding on configuring the interface.
==============================================================================
8: Distribution specific notes
=======================================
===================
8.1: Debian & derivatives
=========
In some instances installing the rt2x00 drivers on debian will result
in the problem that the files are being copied into the wrong folder,
which results in the fact that the driver cannot be loaded.
Installing the drivers should be done manually in this case,
please refer to the distributions documentation regarding the proper
location of the kernel modules.
===================
8.2: Fedora
=========
Although rt2x00 contains many backward compatibility fixes to ensure
that all rt2x00 components will be able to compile and run on all
systems that meet the minimal requirements, this does not work in all
situations when the Fedora kernels are being used.
The problem lies in the fact that Fedora (like most other distributions)
heavily patch their kernel for better stability and more features.
Unlike the other distributions however, Fedora does not pay attention to
compatibility for external kernel drivers. This means that compiling rt2x00
while using a Fedora kernel will result in compile errors regarding unknown
fields in structures or problems with function arguments.
For rt2x00 it is impossible to make all checks to support all Fedora kernel
releases. This means that when rt2x00 compilation is failing while using a
Fedora kernel we cannot give support for the compilation steps.
We recommend the user to complain to the Fedora developers when this problem
occurs.
If the user has managed to compile rt2x00 for a Fedora kernel we will
give support for possible problems while working with rt2x00. So the only
part we do not support is the building of rt2x00.
Please note that when you have edited the rt2x00 code to make it compile,
it is advised to state those changes in bugreports while reporting other
problems with rt2x00.
===================
8.3: Gentoo
=========
rt2x00 can also be found in portage, both the beta releases and the cvs tree.
Because rt2x00 is still experimental these ebuild are still masked, this means
that before you can emerge them they first have to be unmasked.
Gentoo provides various instructions on how this can be done on their website.
===================
8.4: Mandriva
=========
In some instances installing the rt2x00 drivers on Mandriva will result
in the problem that the files are being copied into the wrong folder,
which results in the fact that the driver cannot be loaded.
Installing the drivers should be done manually in this case,
please refer to the distributions documentation regarding the proper
location of the kernel modules.
==============================================================================
9: Problems & Troubleshooting
=======================================
===================
9.1: Debug information
=========
When reporting problems make sure the driver has been compiled with debug
enabled.
If you have done so, the debug output can be found in the output
of 'dmesg' and also in /var/log/messages and /var/log/syslog.
===================
9.2: Debugfs
=========
rt2x00 provides several debugfs entries which can be used to help
provide more information about the interface.
To see the rt2x00 debugfs entries, debugfs should first be mounted,
to do this you should issue the following command:
# $ mount -t debugfs none /debug
Where /debug is the directy on which the debugfs entries should appear,
make sure this directory exists when mounting debugfs.
With the debugfs folder, the rt2x00 folder with the rt2x00 debugfs entries
will be created. Within the rt2x00 folder, each physical device will be
represented by a folder named after the interface which belongs to this
device. Within the folder the following files can be found:
# register
- This file contains the register contents of the interface.
# eeprom
- This file contains the eeprom contents of the interface.
===================
9.3: Bug reporting
=========
When reporting a bug or problem with the rt2x00 module,
make sure you report the following information:
# How to reproduce
# RT2x00 debug output, usually found in /var/log/messages
# Module version
# Wireless card chipset, model and manufacturer
# Kernel version (i.e. 2.6.17)
# Hardware architecture (i.e. x86, AMD64, Sparc)
# rt2x00 code changes done by the user
# Anything else you may think will help us resolve the issue
==============================================================================
10: Problems & Workarounds
=======================================
===================
10.1: udev interface naming
=========
In some cases when loading the rt2x00 drivers the interface names are
different from the names used in this README. This is usually caused by the
udev handler who has set some rules regarding the interface. These rules
are usually set up by the distribution and have been created especially for
for the legacy driver and their strange behavior.
To change the rules udev applies to your interface you should edit the udev
rules stored in /etc/udev/rules.d/ (exact location might be different
depending on distribution).
When editing this file, search for the line that contains something like this:
# ACTION=="add", SUBSYSTEM=="net", DRIVERS=="?*",
# SYSFS{address}=="<mac address>", NAME="<interface>"
(line has been wrapped due to max line length limit)
Where <mac address> is the hardware address of your wireless networkcard,
and <interface> is the interface name the interface takes as soon as the
rt2x00 modules are loaded.
This line should be changed to look like:
# ACTION=="add", SUBSYSTEM=="net", DRIVERS=="?*",
# SYSFS{address}=="<mac address>", SYSFS{type}=="801",
# NAME="wmaster0"
# ACTION=="add", SUBSYSTEM=="net", DRIVERS=="?*",
# SYSFS{address}=="<mac address>", NAME="wlan0"
(the 2 lines have been wrapped due to max line length limit)
Where <mac address> is the hardware address of your wireless networkcard,
and thus should be the same as on the original line.
===================
10.2: BUG - ifdown & ifup radio failure
=========
It is a known issue (and BUG) that the driver will fail to correctly resume
its radio operations after the interface has been brought down and up again.
It is still unknown what the cause for this issue could be, besides the fact
that for some reason the device's registers have been incorrectly initialized.
This issue also has impact on the device status after a suspend/resume
operation. There is no known workaround for this yet.
==============================================================================
11: TODO list
=======================================
See http://rt2x00.serialmonkey.com/wiki/index.php/Rt2x00_beta
==============================================================================
12: Contact us
=======================================
- Website
# http://rt2x00.serialmonkey.com/
# http://rt2x00.serialmonkey.com/wiki/index.php/Rt2x00_beta
- Forums:
# http://rt2x00.serialmonkey.com/phpBB2/
- Mailing list:
# general: rt2400-general@lists.sourceforge.net
# developers: rt2400-devel@lists.sourceforge.net
- Sourceforge:
# http://sourceforge.net/projects/rt2400
8b0dffad62