From 5845db0c4474294335896501e7bef61c9cb56a4c Mon Sep 17 00:00:00 2001 From: Florian Fainelli Date: Tue, 7 Aug 2007 09:12:49 +0000 Subject: 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 --- package/rt2x00/src/README | 548 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 548 insertions(+) create mode 100644 package/rt2x00/src/README (limited to 'package/rt2x00/src/README') diff --git a/package/rt2x00/src/README b/package/rt2x00/src/README new file mode 100644 index 0000000000..7f3f448eaa --- /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 > /sys/class/ieee80211//add_iface + + where the variable is the name of the client interface that should be + added (i.e. wlan1), and 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}=="", NAME="" + (line has been wrapped due to max line length limit) + + Where is the hardware address of your wireless networkcard, + and 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}=="", SYSFS{type}=="801", + # NAME="wmaster0" + # ACTION=="add", SUBSYSTEM=="net", DRIVERS=="?*", + # SYSFS{address}=="", NAME="wlan0" + (the 2 lines have been wrapped due to max line length limit) + + Where 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 + -- cgit v1.2.3