Major rewrite

In particular, list the firmware as a requirement of the driver.

1 files changed, 111 insertions, 73 deletions

diff --git a/README b/README
index ce4a717..1b34105 100644
--- a/README
+++ b/README
@@ -18,8 +18,8 @@ mailing lists and links.
 Hardware Compatibility
 ----------------------
 
-This driver supports USB devices using at76c503, at76c505 and at76c505a
-chipsets.  Known devices with this chip are:
+This driver supports USB devices using Atmel at76c503, at76c505 and
+at76c505a chipsets.  Known devices with this chip are:
 
 - Belkin F5D6050
 - Dynalink/Askey WLL013
@@ -35,6 +35,11 @@ Requirements
 Linux kernel 2.6.x (preferably current) with support for USB and
 wireless networking.
 
+Firmware for your device in the format compatible with this driver.  To
+install the firmware, please read the README file included with the
+firmware package.  The firmware can be downloaded from
+https://developer.berlios.de/projects/at76c503a/
+
 
 Installation
 ------------
@@ -51,64 +56,111 @@ always compile in its source directory.
 When cross-compiling, you may also need to set ARCH and CROSS_COMPILE
 appropriately.  See the top-level kernel Makefile for details.
 
-To install the driver, run "make install" as root.  If you supplied some
+To install the driver, run "make install" as root.  If you supplied any
 extra variables to "make", add them to "make install" as well.
 
-You also need to install the firmware for the device.  Please see the
-download area for the latest firmware package:
-
-https://developer.berlios.de/project/showfiles.php?group_id=727
-
 
 Running
 -------
 
-Plug in the adapter.  If you already used it under Windows or with the
-driver from atmelwlandriver.sourceforge.net, re-plug the device (i.e.
-plug out and in again).
+First of all, please make sure that the firmware is installed.  The
+driver will not work without the firmware.
+
+Once the firmware and the driver are installed, you can connect the
+device.  On most modern distributions, the driver will be loaded
+automatically.  The driver will load the firmware using hotplug or udev
+facility and will create a network interface for each device it finds. 
+
+To make sure that it worked correctly, run "iwconfig".  It will show all
+available wireless interfaces.
+
+To configure the device, use "iwconfig" for wireless specific settings
+and "ifconfig" or "ip" for network settings.
 
-If you have hotplug or udev installed, the driver should now be loaded. 
-If not, load it by hand:
+If you want the device to be configured in a certain way on system
+startup, please use the facilities provided by your distribution.
+
+The driver supports managed, ad-hoc and monitor modes.
+
+
+Troubleshooting
+---------------
+
+If you have any problems with the driver, it's always a good idea to
+check the messages from the kernel.  Use "dmesg" to display them.
+
+If you are not sure whether the driver is loaded, use "lsmod" to see the
+list of the loaded modules.  Look for "at76_usb".  If it's not there,
+load it manually by "modprobe":
 
   modprobe at76_usb
 
-You can give the network device another name than wlanX by giving
-the module the netdev_name parameter, e.g.
+If the driver is loaded but a wireless interface doesn't appear, make
+sure that the firmware is loaded by the driver.  If the driver cannot
+load the firmware, there will be a message from the driver in the kernel
+log.  Make sure that you have a file with exactly that name and that
+it's located in the firmware directory known to hotplug or udev.
 
-  modprobe at76_usb netdev_name=eth%d
+If you see a wireless interface but you are not sure which driver
+created it, use "ethtool -i wlanX", where "wlanX" is the interface name.
+
+If the interface is up, but "iwconfig" shows that it's not associated to
+an access point, make sure that the card is in managed mode and that it
+uses the same ESSID and WEP key as the access point you want to connect
+to.  If using WEP, make sure you are using an authentication method
+supported by the access point.
+
+When in the ad-hoc mode, make sure that all the participants are using
+the same channel.
+
+To learn about available access points, use "iwlist wlanX scan" where
+"wlanX" is the interface name.
+
+WPA is not currently supported by this driver, so you cannot connect to
+access points with WPA enabled.
+
+
+Module Parameters
+-----------------
 
-would give the first device the name eth0, the second eth1 and so on. 
 You can use "modinfo at76_usb" to see the complete list of the supported
-parameters with descriptions.
+parameters with descriptions.  Use module parameters on the "modprobe"
+command line.  If the "at76_usb" module is loaded already, unload it
+first with "modprobe -r at76_usb".
 
-Use lsmod to check if the module is loaded.  It should look like this:
+Once you know which parameters you need, use the "options" command in
+/etc/modprobe.conf to use them every time the module is loaded.
 
-  Module                  Size  Used by
-  at76_usb               99432  0 
+For example, you can give the network device another name than wlanX by
+giving the module the "netdev_name" parameter:
 
-Setup networking (replace <iface> with wlan0, wlan1, ..., <ch> with a
-channel number (1..14) <essid> with your network id (a string), <ip>
-with an IP address)
+  modprobe at76_usb netdev_name=eth%d
 
-  iwconfig <iface> channel <ch> mode ad-hoc essid <essid>
-  ifconfig <iface> <ip>
+If this parameter is used, the first device would be eth0 (unless it's
+already used by another driver, of course), the second eth1 and so on. 
 
-Example:
 
-  iwconfig wlan2 mode ad-hoc channel 10 essid okuwlan
-  ifconfig wlan2 192.168.0.4
+Private Parameters
+------------------
 
-Test it by pinging another host with a WLAN adapter.
+In addition to the wireless parameters set by "iwconfig", there are
+additional driver-specific parameters available via "iwpriv".  Running
+"iwpriv wlanX" will list all of them.
 
-Note that the firmware survives reboots of the computer, but not
-unplugging the device.
+Following are some of the supported parameters:
 
-If you get problems, run dmesg to see if there are error messages it
-will also show the firmware version.
+- long preamble: iwpriv wlanX short_preamble 0
+- short preamble: iwpriv wlanX short_preamble 1
+- amount of debug messages: iwpriv wlanX set_debug N
+  with N a combination of bits, see DBG_* in at76c503.h
+- power save mode: iwpriv wlanX powersave_mode N (numbers 1, 2, 3 for
+  for none, save and smart save respectively)
+- scan channel time: iwpriv wlanX scan_times <min_ch_time> <max_ch_time>
+  (this may be required for 0.90.x firmware, i.e. Intersil radios)
 
 
-Power Save Modes in Infrastructure Mode
----------------------------------------
+Power Save Modes in Managed Mode
+--------------------------------
 
 You can activate 802.11 power save mode by executing
 
@@ -135,60 +187,46 @@ can only set it earlier by iwconfig, e.g.
    iwpriv wlanX powersave_mode 3
 
 
-Private Parameters
-------------------
-
-In addition to the parameters of iwconfig, some can be set by iwpriv:
-
-- long preamble: iwpriv wlanX short_preamble 0
-- short preamble: iwpriv wlanX short_preamble 1
-- amount of debug messages: iwpriv wlanX set_debug N
-  with N a combination of bits, see DBG_* in at76c503.c
-- power save mode: iwpriv wlanX powersave_mode N (numbers 1, 2, 3 for
-  for none, save and smart save respectively)
-- scan channel time: iwpriv wlanX scan_times <min_ch_time> <max_ch_time>
-  (this may be required for 0.90.x firmware, i.e. Intersil radios)
-
-Beware that shared key authentication requires a WEP key.
-
-
 Known Problems
 --------------
 
 1) Bugs of the firmware 0.90.0-44 (the latest available for device with
-  Intersil radio after Atmel stopped support for Intersil radio
-  chipsets):
+   Intersil radio after Atmel stopped support for Intersil radio
+   chipsets):
 
-  - active scan doesn't send ProbeReq neither in ad-hoc or in
-    infrastructure (managed) mode
+  - active scan doesn't send ProbeReq either in ad-hoc or in managed    
+    mode
 
     * If your ad-hoc peer sends the beacon in longer intervals,
       the Atmel driver may not find it. Try to increase the max
       channel time to 500 or 1000 (default 120) by calling
+
               iwpriv wlanX scan_times 10 <max channel time>
-      If you found a working value, add the module parameter
-      scan_max_time to /etc/modules.conf .
 
-    * You cannot connect to an access point which hides its SSID and
+      If you found a working value, use the module parameter
+      scan_max_time.
+
+    * You cannot connect to an access point which hides its ESSID and
       requires the STA to probe it!
 
-  - After joining an existing IBSS of a 2MBit card, the basic rates are
-    wrong in the beacon, e.g.
-    a 2 MBit card broadcasts a basic rate set of 1 + 2 MBit/s,
-    but the Atmel device sends out basic rates of 1,2,5.5 and 11 MBit/s
-    Subsequently it cannot connect to the 2 MBit card, because it sends
-    it's data packets to broadcast addresses with 11 MBit/s.
+  - After joining an existing IBSS of a 2 Mbps card, the basic rates are
+    wrong in the beacon, e.g. a 2 Mbps card broadcasts a basic rate set
+    of 1 + 2 Mbps, but the Atmel device sends out basic rates of 1, 2,
+    5.5 and 11 Mbps.  Subsequently it cannot connect to the 2 Mbps card,
+    because it sends it's data packets to broadcast addresses with 11
+    Mbps.
 
   - power saving modes does not work
 
 2) firmware 1.101.0-84
-  - if a 2MBit card joins an IBSS (ad-hoc mode) initiated by the Atmel
-    device (which currently broadcasts 1+2 MBit/s as the basic rates
-    and 5.5 and 11 MBit/s as (additional) operational rates), the
-    Atmel device sends out broadcast packets (e.g. ARP requests) with
-    11 MBit/s. This may be fixed by changing the tx rate in iwconfig
-    from "auto" (default) to 1M or 2M.
-    I'm not sure if this is a firmware bug or a problem in the driver.
+
+  - if a 2 Mbps card joins an IBSS (ad-hoc mode) initiated by the Atmel
+    device (which currently broadcasts 1 + 2 Mbps as the basic rates and
+    5.5 and 11 Mbps as (additional) operational rates), the Atmel device
+    sends out broadcast packets (e.g. ARP requests) with 11 Mbps.  This
+    may be fixed by changing the tx rate in iwconfig from "auto"
+    (default) to 1M or 2M.  I'm not sure if this is a firmware bug or a
+    problem in the driver.
     
 
 Credits