mirror of https://github.com/proski/madwifi
381 lines
15 KiB
Plaintext
381 lines
15 KiB
Plaintext
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.
|
|
|
|
|
|
WARNING: THIS IS A BETA DISTRIBUTION. THIS SOFTWARE HAS KNOWN PROBLEMS
|
|
WARNING: AND LIMITATIONS THAT WILL BE CORRECTED BEFORE A PRODUCTION
|
|
WARNING: RELEASE. DON'T BLAME US IF THE SOFTWARE EATS YOUR SYSTEM,
|
|
WARNING: DESTROYS YOUR DISK OR MAKES YOUR CORN-FLAKES SOGGY.
|
|
WARNING: USE AT YOUR OWN RISK!
|
|
|
|
|
|
Introduction
|
|
------------
|
|
|
|
This software contains a Linux kernel driver for Atheros-based Wireless
|
|
LAN devices. The driver supports station, AP, ad-hoc, 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).
|
|
|
|
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 PCI, MiniPCI and
|
|
Cardbus devices - USB devices are currently not supported by this
|
|
driver! 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
|
|
this is the case on BSD systems).
|
|
|
|
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_xauth). 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 the
|
|
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".
|
|
|
|
A detailed discussion of the pros and cons of this design can be found
|
|
at http://madwifi-project.org/wiki/HAL
|
|
|
|
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.
|
|
|
|
|
|
Atheros Hardware
|
|
----------------
|
|
|
|
There are currently three "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 D-Link, 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
|
|
built-in wireless support.
|
|
|
|
For an up-to-date list of cards based on Atheros parts visit:
|
|
http://customerproducts.atheros.com/customerproducts
|
|
|
|
A list of products that have been reported to be supported by MadWifi
|
|
can be found here:
|
|
http://madwifi-project.org/wiki/Compatibility
|
|
|
|
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 some vendors use alternate vendor IDs (e.g 3Com, IBM).
|
|
The file ath_hal/ah_devid.h has a list of known PCI IDs.
|
|
|
|
|
|
Building the driver
|
|
-------------------
|
|
|
|
The procedure to build the driver is described in the file INSTALL.
|
|
|
|
|
|
Using the driver
|
|
----------------
|
|
|
|
The driver should support any Atheros-based Cardbus or PCI device. This
|
|
version of the driver is managed and controlled by the usual Linux tools
|
|
(ifconfig, iwconfig, iwpriv) plus the wlanconfig tool, which is included
|
|
with the driver in the tools directory and gets installed on your system
|
|
with make install.
|
|
|
|
First, run "modprobe ath_pci" or the equivalent using "insmod". When
|
|
the driver is successfully loaded it creates two devices, named "wifi0"
|
|
and "ath0". The output from iwconfig should look like this:
|
|
|
|
lo no wireless extensions.
|
|
|
|
wifi0 no wireless extensions.
|
|
|
|
ath0 IEEE 802.11b ESSID:""
|
|
Mode:Managed Channel:0 Access Point: Not-Associated
|
|
Bit Rate:0 kb/s Tx-Power:50 dBm Sensitivity=0/3
|
|
Retry:off RTS thr:off Fragment thr:off
|
|
Power Management:off
|
|
Link Quality=0/94 Signal level=-95 dBm Noise level=-95 dBm
|
|
Rx invalid nwid:0 Rx invalid crypt:0 Rx invalid frag:0
|
|
Tx excessive retries:0 Invalid misc:0 Missed beacon:0
|
|
|
|
|
|
This driver uses wifi%d only as a placeholder for the physical device,
|
|
and will create one wifi device for each wireless NIC in the system.
|
|
These wifi devices will reject ifconfig and iwconfig commands. The wifi
|
|
interface indicates the existence of a physical MadWifi device, but it
|
|
is not of any functional interest other than as the starting point for
|
|
VAP creation via wlanconfig (see Virtual AP section below).
|
|
|
|
By default, an ath%d Managed mode interface is also created. This
|
|
device is a "virtual ap" (VAP) of the wifi%d physical device, and is
|
|
configurable by the standard networking tools - ifconfig, iwconfig,
|
|
iwpriv.
|
|
|
|
The autocreation function can be manipulated to create any one of the
|
|
other supported device types automatically by using the autocreate=mode
|
|
option when the ath_pci module is first loaded. The following example
|
|
will cause ath%d to be in Master mode:
|
|
|
|
modprobe ath_pci autocreate=ap
|
|
|
|
Autocreation can be disabled:
|
|
|
|
modprobe ath_pci autocreate=none
|
|
|
|
Please see the following link for more information:
|
|
http://madwifi-project.org/wiki/UserDocs/autocreate
|
|
|
|
|
|
Virtual APs (VAPs) and wlanconfig
|
|
---------------------------------
|
|
|
|
An interesting feature of MadWifi is Virtual AP (VAP) mode, which allows
|
|
the operation of multiple concurrent (virtual) access points, and
|
|
concurrent interfaces running in both AP and station mode. To
|
|
manipulate VAPs, MadWifi comes with a tool called wlanconfig which is
|
|
used to create and destroy VAPS with various different modes.
|
|
|
|
The following examples assume that the "autocreate=none" option has been
|
|
parsed to the module at load time. This allows fine control over
|
|
management of VAPs, as the creation of a Managed mode station should be
|
|
delayed until all other required VAPs are first created, as only one
|
|
sta mode VAP can exist per physical device.
|
|
|
|
To create an access point, use:
|
|
|
|
wlanconfig ath0 create wlandev wifi0 wlanmode ap
|
|
|
|
To create an access point and a station, use:
|
|
|
|
wlanconfig ath0 create wlandev wifi0 wlanmode ap
|
|
wlanconfig ath1 create wlandev wifi0 wlanmode sta
|
|
|
|
To create APs that share a single MAC address, just create the VAPs:
|
|
|
|
wlanconfig ath0 create wlandev wifi0 wlanmode ap
|
|
wlanconfig ath1 create wlandev wifi0 wlanmode ap
|
|
|
|
To create an VAP with a unique MAC address, use the bssid parameter:
|
|
|
|
wlanconfig ath0 create wlandev wifi0 wlanmode ap
|
|
wlanconfig ath1 create wlandev wifi0 wlanmode ap bssid
|
|
|
|
Finally, to destroy a VAP, issue the command:
|
|
|
|
wlanconfig ath0 destroy
|
|
|
|
For more information about Virtual APs, please refer to the users-guide
|
|
document distributed with the MadWifi source code.
|
|
|
|
For more information about wlanconfig, see its manpage, it is installed
|
|
when you run "make install".
|
|
|
|
|
|
Operating Mode
|
|
--------------
|
|
|
|
If you have a multi-mode card, use one of the following commands to lock
|
|
the operating mode to one of 11a, 11b, or 11g:
|
|
|
|
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)
|
|
|
|
|
|
Debugging
|
|
---------
|
|
|
|
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.
|
|
|
|
A more comfortable way to manipulate the debug settings is to make use
|
|
of athdebug and 80211debug tools. Call them with the parameter "-h" to
|
|
learn how they are used, or refer to the appropriate man pages.
|
|
|
|
In addition the programs tools/athstats and tools/80211stats can be very
|
|
useful in understanding what is going on. In particular, something like
|
|
|
|
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.
|
|
By default the ath0 device is used; to override this use the -i option.
|
|
|
|
A wiki page describes common MadWifi debugging methods here:
|
|
http://madwifi-project.org/wiki/DevDocs/AthDebug
|
|
|
|
|
|
Security/Crypto 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 be 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.
|
|
|
|
MadWifi supports the use of the Wireless Extensions ioctls equal to or
|
|
greater than WE18 (Linux 2.6.13). When using wpa_supplicant with a
|
|
recent linux kernel, it is preferred to use the 'wext' driver backend,
|
|
rather than the private MadWifi ioctls. This means that '-D wext'
|
|
option should be used with wpa_supplicant.
|
|
|
|
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 and/or
|
|
802.1x authentication. The authentication mode is specified using
|
|
iwpriv:
|
|
|
|
iwpriv ath0 authmode 1 # open authentication
|
|
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 from.
|
|
Consult the hostapd documentation for further information.
|
|
|
|
|
|
Live Monitoring and Writing Raw 802.11 Packets
|
|
----------------------------------------------
|
|
|
|
The driver can be used in a live "monitor" mode, by creating a monitor
|
|
VAP and sending packets to it. All packets sent to a monitor mode VAP
|
|
will bypass any state machine.
|
|
|
|
To create a monitor VAP, use:
|
|
|
|
wlanconfig ath1 create wlandev wifi0 wlanmode monitor
|
|
ifconfig ath1 up
|
|
|
|
Finally, you can choose to receive packets on ath1 in several different
|
|
packet formats:
|
|
|
|
echo '801' > /proc/sys/net/ath1/dev_type # only 802.11 headers
|
|
echo '802' > /proc/sys/net/ath1/dev_type # prism2 headers
|
|
echo '803' > /proc/sys/net/ath1/dev_type # radiotap headers
|
|
echo '804' > /proc/sys/net/ath1/dev_type # atheros descriptors
|
|
|
|
|
|
Known Problems
|
|
--------------
|
|
|
|
[All these problems are to be fixed in future revisions.]
|
|
|
|
1. Ad-hoc mode is broken; symptoms are intermittent operation.
|
|
|
|
Other issues might be mentioned in our ticket tracker:
|
|
http://madwifi-project.org/report/1
|
|
|
|
|
|
Getting Support
|
|
---------------
|
|
|
|
User support is provided via the madwifi-users mailing list, which can
|
|
be reached at:
|
|
|
|
madwifi-users@lists.sourceforge.net
|
|
|
|
Contact this mailing list if you need help in getting your installation
|
|
up and running. We suggest that you subscribe to the list before
|
|
sending your request (see below).
|
|
|
|
We also offer an IRC channel that might be a better help in urgent
|
|
cases. Learn more about the different ways to get support by visiting:
|
|
|
|
http://madwifi-project.org/wiki/Support
|
|
|
|
When sending a support request or 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, without any promise of support.
|
|
|
|
|
|
Feedback and Contributions
|
|
--------------------------
|
|
|
|
Reports about reproducible bugs, feature requests and patches should be
|
|
submitted in the form of a trouble ticket:
|
|
|
|
http://madwifi-project.org/wiki/TicketSubmissionGuidelines
|
|
|
|
Fixes and enhancements are encouraged.
|