summaryrefslogtreecommitdiffstats
path: root/package/rt2x00/src/README
diff options
context:
space:
mode:
authorflorian <florian@3c298f89-4303-0410-b956-a3cf2f4a3e73>2007-08-07 09:12:49 +0000
committerflorian <florian@3c298f89-4303-0410-b956-a3cf2f4a3e73>2007-08-07 09:12:49 +0000
commite141a9231dc8a20e7ba6e2dd0b29b4f1082ed094 (patch)
tree704340b18ee1594a3af47d6d525c3473edc42572 /package/rt2x00/src/README
parent96455c222d2b7bc4033fc43ffd0411684faba4fc (diff)
Upgrade rt2x00 to a more recent snapshot, master mode now working, thanks to Daniel Gimpelevich
git-svn-id: svn://svn.openwrt.org/openwrt/trunk@8367 3c298f89-4303-0410-b956-a3cf2f4a3e73
Diffstat (limited to 'package/rt2x00/src/README')
-rw-r--r--package/rt2x00/src/README548
1 files changed, 548 insertions, 0 deletions
diff --git a/package/rt2x00/src/README b/package/rt2x00/src/README
new file mode 100644
index 000000000..7f3f448ea
--- /dev/null
+++ b/package/rt2x00/src/README
@@ -0,0 +1,548 @@
+===============================================================================
+ 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
+