===============================================================================
 Installation and configuration instructions for the rt2x00 Modules
===============================================================================

===============================================================================
 Table of contents:
========================

 - 1: Minimal requirements
   - 1.1: kernel
   - 1.2: gcc
   - 1.3: d80211 stack
 - 2: Hardware
   - 2.1: Chipsets
   - 2.2: RF button
 - 3: Module building
   - 3.1: Configure
   - 3.2: Build
 - 4: Module installation
 - 5: Firmware
   - 5.1: Firmware files
   - 5.2: Firmware installation
   - 5.3: Firmware requirements
 - 6: Module loading
   - 6.1: Module load order
   - 6.2: Module load options
 - 7: Interfaces
   - 7.1: Wireless interfaces
   - 7.2: Input interface
 - 8: Interface configuration
 - 9: Distribution specific notes
   - 9.1: Debian & derivatives
   - 9.2: Fedora
   - 9.3: Gentoo
   - 9.4: Mandriva
 - 10: Problems & Troubleshooting
   - 10.1: Debug information
   - 10.2: Ethtool
   - 10.3: Bug reporting
 - 11: Contact us


===============================================================================
 1: Minimal requirements:
=======================================

===================
 1.1: kernel
=========

 - The minimal required kernel version is 2.6.17

 - 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_PCI			rt2400pci, rt2500pci, rt61pci
	# CONFIG_USB			rt2500usb, rt73usb
	# CONFIG_FW_LOADER		rt61pci, rt73usb
	# CONFIG_INPUT			rfkill
	# CONFIG_CRYPTO			d80211
	# CONFIG_CRYPTO_AES		d80211
	# CONFIG_CRYPTO_AES_586 	d80211 (optional, only for x86)
	# CONFIG_CRYPTO_AES_X86_64	d80211 (optional, only for x86_64)
	# CONFIG_CRYPTO_ARC4		d80211

===================
 1.2: GCC
=========

 - For building the rt2x00 components the same gcc version is required
   as was used to build your target kernel.

===================
 1.3: d80211 stack
=========

 - rt2x00 depends on the d80211 stack which was originally developed by
   Devicescape. Currently this stack is being actively maintained by
   Jiri Benc. The latest version of this stack can be found in the
   'ieee80211' folder of the rt2x00 module source.


===============================================================================
 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: 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. To support this feature the rfkill driver
 is required.
 If you have such a hardware device, make sure you enable the rfkill driver and
 hardware button support for your device in the configuration before building
 the rt2x00 components.


===============================================================================
 3: Module building
=======================================

===================
 3.1: 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 and the d80211 module (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.2: 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.


===============================================================================
 4: Module 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)/').


==============================================================================
 5: Firmware
=======================================

===================
 5.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

===================
 5.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.
 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.

===================
 5.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.

==============================================================================
 6: Module loading
=======================================

===================
 6.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:

	# 80211.ko
	# rate_control.ko
	# rfkill.ko (optional, only required for Hardware button support)
	# crc-itu-t.ko (optional, only required for rt61 and rt73 support)
	# 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)

===================
 6.2: Module load options
=========

 - option: debug
 - allowed values: 0, 1
 - description:
   This option is only available when the module has been compiled
   with debug capabilities enabled (this is the default build behaviour).
   Debug output can be disabled by setting this value to 0 (default),
   and it can be enabled by setting this value to 1.
   After the module has been loaded this variable can be changed dynamically
   by writing 0 (or 'N') to disable or 1 (or 'Y') to the file
   /sys/module/<modulename>/parameters/debug.
   Where <modulename> is the device specific driver name (i.e. rt2400pci).


==============================================================================
 7: Interfaces
=======================================

===================
 7.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).

===================
 7.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.


==============================================================================
 8: Interface configuration
=======================================

 - After loading the modules the interface should be configured to start
 an association or work in monitor mode.

 - 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. Note that it is currently
   mandatory to scan at least once before starting an association attempt.

	# $ iwlist wlan0 scan

 - To start an association attempt, the AP address should be set:

	# $ iwconfig wlan0 ap mybssid


==============================================================================
 9: Distribution specific notes
=======================================

===================
 9.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.

===================
 9.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.

===================
 9.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.

===================
 9.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.


==============================================================================
 10: Problems & Troubleshooting
=======================================

===================
 10.1: Debug information
=========

 When reporting problems make sure you have loaded the driver with debug output
 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.

===================
 10.2: Ethtool
=========

 Support for several ethtool functions is supported in rt2x00.
 When using ethtool, the master interface (wmaster0) and not the client
 interface should be passed to ethtool.
 The features rt2x00 provide are:

	# ethtool -i
		- Information about the driver.

	# ethtool -d
		- A dump of the devices CSR register is returned.

	# ethtool -e
		- A dump of the devices EEPROM contents is returned.

	# ethtool -s msglvl X
		- This option is only available when the driver was build with
		- debug enabled.
		- Replace X with 1 or 0 to enable or disable respectively
		- the rt2x00 debug output. This is an alternative for setting
		- the module parameter.

===================
 10.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


==============================================================================
 11: 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