$Id: README,v 1.34 2005/08/14 17:03:52 jbicket Exp $ WARNING: THIS IS A BETA DISTRIBUTION. THIS SOFTWARE HAS KNOWN PROBLEMS AND WARNING: LIMITATIONS THAT WILL BE CORRECTED BEFORE A PRODUCTION RELEASE. WARNING: DON'T BLAME US IF THE SOFTWARE EATS YOUR SYSTEM, DESTROYS YOUR DISK WARNING: OR MAKES YOUR CORN-FLAKES SOGGY. WARNING: USE AT YOUR OWN RISK! MADWIFI: Multimode Atheros Driver for WiFi on Linux ================================================================ * Copyright (c) 2002-2005 Sam Leffler. All rights reserved. Read the file COPYRIGHT for the complete copyright. This software contains a Linux kernel driver for Atheros-based Wireless LAN devices. The driver supports station, AP, adhoc, and monitor modes of operation. The Atheros driver depends on a device-independent implementation of the 802.11 protocols that originated in the BSD community (NetBSD in particular). You will find a small amount of BSD-ish glue code that exists mainly to minimize diffs with the BSD variants. However as much as possible this is "native Linux code" that tries to conform to Linux style and operation. The driver functions as a normal network device and uses the Wireless Extensions API. As such normal Linux tools can and should be used with it. Where the wireless extensions are lacking private ioctls have been added. There is only one driver included here; it supports both miniPCI and Cardbus devices. The driver can be built as a module or linked directly into the kernel. Note however that the net80211 layer is device-independent; there is no reason it cannot be used with any 802.11 device (in fact on BSD systems this is the case). This software is broken into multiple modules. The Atheros-specific device support is found in the ath_pci module; it should be loaded when an Atheros wireless device is recognized. The ath_pci module requires an additional device specific module, ath_hal, which is described more below. In addition the driver requires the wlan module which contains the 802.11 state machine, protocol support, and other device-independent support needed by any 802.11 device. This code is derived from work that first appeared in NetBSD and then FreeBSD. The wlan module may also force the loading of additional modules for crypto support (wlan_wep, wlan_tkip, wlan_ccmp, etc.), for MAC-based ACL support (wlan_acl), and for 802.1x authenticator support (wlan_auth, wlan_radius)). The latter modules are only used when operating as an AP. The crypto modules are loaded when keys of that type are created. The ath_hal module contains the Atheros Hardware Access Layer (HAL). This code manages much of the chip-specific operation of the driver. The HAL is provided in a binary-only form in order to comply with FCC regulations. In particular, a radio transmitter can only be operated at power levels and on frequency channels for which it is approved. The FCC requires that a software-defined radio cannot be configured by a user to operate outside the approved power levels and frequency channels. This makes it difficult to open-source code that enforces limits on the power levels, frequency channels and other parameters of the radio transmitter. See http://ftp.fcc.gov/Bureaus/Engineering_Technology/Orders/2001/fcc01264.pdf for the specific FCC regulation. Because the module is provided in a binary-only form it is marked "Proprietary"; this means when you load it you will see messages that your system is now "tainted". If you wish to use this driver on a platform for which an ath_hal module is not already provided please contact the author. Note that this is only necessary for new _architectures_; the HAL is not tied to any specific version of Linux--in fact the identical HAL binary code is used unchanged with other operating systems. Driver status ------------- At the moment there exist no stable releases for madwifi project. We are working on it but for now only the sourceforge cvs and daily snapshots at http://madwifi.otaku42.de/ exist. The following list is updated incrementally. Only if a feature has proven to be stable it is marked "OK". Super AG ??? Atheros XR ??? Virtual AP ??? 802.11e (QoS) ??? 802.11h (DFS, TPC) ??? WDS support ??? Power Safe mode ??? WPA 1/2 AP support (hostapd) ??? Managed mode (client) ??? Master mode (AP) ??? Ad-Hoc mode ??? Monitor/Promiscuous mode ??? Throughput 802.11b ??? (specs) Throughput 802.11g ??? (specs) Throughput 802.11a ??? (specs) Kismet support ??? Linux Wireless API Support ??? Platform independence ??? Full Linux Wireless compat ??? SMP-safe ??? ACPI support ??? Atheros Hardware ================ There are currently 3 "programming generations" of Atheros 802.11 wireless devices (some of these have multiple hardware implementations but otherwise appear identical to users): 5210 supports 11a only 5211 supports both 11a and 11b 5212 supports 11a, 11b, and 11g These parts have been incorporated in a variety of retail products including cardbus cards from DLink, Linksys, Netgear, Orinoco, Proxim, and 3Com; and mini-pci cards from some of these same vendors. In addition many laptop vendors use Atheros mini-pci cards for their builtin wireless support. For an up-to-date list of cards based on Atheros parts visit: http://customerproducts.atheros.com/customerproducts In general, if a device is identified as ``11a only'' it is almost certain to contain an Atheros 5210 part in it. Most retail a+b products use the 5211. Many a+b+g combo products use the 5212 though other vendors have started to offer dual-band support. When in doubt check the PCI vendor id with a tool like lspci, the Atheros vendor id is 0x168c; e.g. 00:13.0 Ethernet controller: Unknown device 168c:0012 (rev 01) but beware that come vendors use alternate vendor id's (e.g 3Com, IBM). The file hal/ah_devid.h has a list of known PCI id's. Using the driver ================ The driver should support any Atheros-based cardbus or pci device. Management is done using the normal Linux tools such as ifconfig, iwconfig, and iwpriv. To use this software in ``station mode'' (i.e. as a client) just bring the interface up and the driver will scan for all access points in all supported frequency bands supported by the hardware. Specifically for 5210-based devices scanning will happen in the 5Ghz (11a) range, for 5211-based devices scanning will happen over both 2Ghz (11b) and 5GHz frequencies (11a). For 5212-based devices the driver will scan both 2Ghz and 5GHz ranges and also look for 11g devices in the 2Ghz range. To restrict operation you can either select a mode (e.g. 11b) using iwpriv or, more commonly, select the AP based on SSID and/or channel. NOTE: You must mark the interface ``up'' with, e.g. ifconfig ath0 up before scanning for access points with iwlist. To use this software in ``hostap mode'' you need to configure it with iwconfig and you will probably want to lock the operating mode to one of 11a, 11b, or 11g if you have a multi-mode card (if you do not lock the mode then the driver will select a mode for you; usually 11a). In addition you will need to configure the system to bridge frames to a wired LAN or similar. Wireless tools cribsheet: iwlist ath0 scan list AP's the driver has scanned iwconfig ath0 essid "foo" set the ssid to foo iwpriv ath0 mode 1 lock operation to 11a only iwpriv ath0 mode 2 lock operation to 11b only iwpriv ath0 mode 3 lock operation to 11g only iwpriv ath0 mode 0 autoselect from 11a/b/g (default) There are some debugging mechanisms for the curious/masochistic: sysctl -w dev.ath.debug=0xXXX enable console msgs from the driver sysctl -w net.wlan0.debug=0xYYY enable console msgs from the wlan module The values specified for 0XXX and 0xYYY are bit masks that enable debugging in various parts of each module. For the wlan module these values are found in the file net80211/ieee80211_var.h (search for MSG_). For the ath driver look in ath/if_ath.c (search for ATH_DEBUG). Beware that enabling some debugging msgs can affect the operation of the software by slowing it down too much. The programs tools/athdebug and tools/80211debug allow you to do the above using symbol names; e.g. athdebug +xmit 80211debug scan+assoc In addition the programs tools/athstats and tools/80211stats can be very useful in understanding what is going on. In particular, something like: trouble% athstats 1 will give a running display of the most interesting statistics sampled every 1 second. Running athstats without any options will display a summary of all non-zero statistics from the time the driver was loaded. NOTE: By default the ath0 device is used; to override this use the -i athX option. Security/Crpto Support ====================== All Atheros devices implement fixed/shared key WEP in hardware. Newer Atheros hardware is capable of much more (e.g. AES, TKIP and Michael). When hardware support is not available for a cipher the net80211 layer will automatically do the work in software. WPA/802.11i station operation (aka supplicant) is supported using Jouni Malinen's wpa_supplicant program. This can obtained from: http://hostap.epitest.fi/wpa_supplicant/ wpa_supplicant also supports a wide range of 802.1x EAP methods, either together with WPA/WPA2 or without; consult the wpa_supplicant documentation for an up to date list. NOTE: the in-kernel authenticator is being replaced; to use it you need to follow the directions in net80211/Makefile. When operating as an AP you can use fixed/shared key ciphers, 802.1x, and/or WPA authentication. The authentication mode is specified using iwpriv: iwpriv ath0 authmode 1 # open authenticatoin iwpriv ath0 authmode 2 # shared key authentication iwpriv ath0 authmode 3 # 802.1x authentication To use the 802.1x authenticator you must install and configure the hostapd program from the same place you got wpa_supplicant. Consult the hostapd documentation for its' setup. Live Monitoring and Writing Raw 802.11 Packets ============================================== The driver can be used in a live "monitor" mode via the ath0raw device. To turn on the device you must run the following: sysctl -w dev.ath0.rawdev=1 # create ath0raw ifconfig ath0raw up # start receiving packets on ath0raw This will create a ath0raw device. You can send packets to the device and they will be sent directly to the card, bypassing any state machine. Finally, you can choose to receive packets on ath0raw in a number of different packet formats: sysctl -w dev.ath0.rawdev_type=0 # normal 802.11 frames (default) sysctl -w dev.ath0.rawdev_type=1 # prism headers + 802.11 sysctl -w dev.ath0.rawdev_type=2 # radiotap + 802.11 Known Problems ============== [All these problems are to be fixed in future revisions.] 1. Performance in lossy environments is suboptimal. The algorithm used to select the rate for transmitted packets is very simplistic. There is no software retransmit; only hardware retransmit is used. Contributors are encouraged to replace the existing rate control algorithm with a better one (hint: all the information needed is available in the driver). Acknowledgements ================ This work could not have been done without the support of Atheros and in particular the efforts of Greg Chesson. Comments from David Miller were helpful in cleaning up some of the roughest edges in early versions of the driver. Many people have contributed fixes and improvements to this software including: Joerg Albert Mathieu Lacage Henry Qian giova+mwfdev@fagl Vivien Chappelier Eric Lammerts Mark Rakes Stephen Walton Tong Chia Stephane Laroche Michael Renzmann Dale Whitfield Joachim Gleissner Georg Lukas Paul Stewart Alexander Wirtz Guy Erb Tom Marshall D. Stolte Kevin Yu Kristian Hoffmann Nick Moss Bindu Therthala Thorsten von Eicken William S. Kish Nick Petroni Carl Thompson Jouni Malinen Satish Balay Richard Dawe Bruno Randolf Sebastian Weitzel Rajendra Singh Tai-hwa Liang Divy Le Ray John Bicket Takayuki Kaiso Owen Stampflee (Apologies to anyone whose name was unintentionally left off.) Feedback and Contributions ========================== This project is hosted at http://madwifi.sourceforge.net. Fixes and enhancements are encouraged. Please send all bug reports about this driver to: madwifi-users@lists.sourceforge.net When sending a problem report be sure to include the version of the driver and the part identification the driver prints to the console when the module is loaded. For example, ath_hal: 0.8.2.0 wlan: 0.7.0.0 ath_pci: 0.8.2.0 PCI: Found IRQ 11 for device 00:13.0 ath0: 11a rates: 6Mbps 9Mbps 12Mbps 18Mbps 24Mbps 36Mbps 48Mbps 54Mbps ath0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps ath0: 802.11 address: 00:05:5d:6f:99:5f ath0: Atheros 5211: mem=0xfebf0000, irq=11 This says the HAL module is version 0.8.2, the wlan module is version 0.7, the driver is version 0.8.2 and the hardware uses an Atheros 5211 chip (which supports 11a and 11b modes). We will try to respond in a timely manner but understand this software is provided as-is; i.e. with no promise of support.