freifunkist-firmware/package/rt2x00/src

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