Original 0.2.0pre8_plus_fixes_8 tarball

[acx-mac80211.git] / README

*******************************************************************************
*             Open-Source wireless driver for TI ACX1xx chipsets              *
*******************************************************************************

WARNING: this driver may still cause your box to lockup in very rare cases!
If this happens, then please report at/create a bug report!

RELIABILITY WARNING: The DWL-650+ seems to have a slightly too high
defect rate (see doc/general_info). Consider buying any card with FCC ID
O7J-GL242201 (0 defect reports) instead of the DWL-650+ (5+ defect/problem
reports). One might attribute this to the higher sales numbers of the
DWL-650+, but I'm not quite sure...

Please NEVER consider using the NDIS driver loader cludge instead of our driver.
For an incredible number of reasons against it, please see
http://acx100.sourceforge.net/ndis_cludge.html
If for some or another reason you're unhappy with the performance of our
current driver version, then either fix it if you're capable of doing that
or immediately think of returning to the shop or, if that is not possible,
of selling your very poorly supported Taxed Sinstruments based card in
exchange for a wireless card that is well-supported under Linux.
Buying the very problematic DriverLoader product instead in an attempt
to "fix" missing Linux driver support will send the entirely wrong message to
wireless card manufacturers, so please never choose to do that.
There are many commercial products very much worth buying; but this is
certainly not one of those...

Also, please take note that I learnt that TI is using and supporting
Linux for at least TNETW1230 driver SDKs and Linux QoS management (only
commercially available, I suppose?).
However somehow they're still too elitist to actually pass (parts of) that
Linux infrastructure back to the desperate end users looking for proper
TNETW1xxx driver support, even after continuous user requests.
Returning such completely improperly supported WLAN hardware to the shop
and mentioning unacceptable terms suddenly doesn't sound like such a
chore any more...

--- CARD COMPATIBILITY (aka "the real dirt") ---

Let us first mention that this driver is supposed to support EVERY SINGLE CARD
with ACX100 chip (except for USB and Compact Flash implementations,
which are both extremely rare -- USB support exists for both
2.4.x and 2.6.x, however it may be not completely "stable" yet). [040523]
If the driver doesn't work with your ACX100 card, then please notify us
immediately after you followed *EVERY ADVICE IN THIS FILE* (and elsewhere)
and are at your wits end as to what might still make the card fail
(and make sure to try previous versions of the driver as well!).

Other Texas Instruments chips which are e.g. 802.11g capable and may be named
TNETW1130/1230 (ACX111) only just started to actually be supported in a useful
way by this driver [040523].

Also, due to confusion about similar card naming (for further information, see
bottom), people keep thinking certain cards they own work with this driver.
Cards that are *NOT* based on ACX1xx chipset (as opposed to the stupidly
similarly named ACX1xx versions DWL-120+, DWL-520+ and DWL-650+, which *do*
have ACX1xx) are:

DWL-120 (PRISM2 chipset)
DWL-520 (PRISM2)
DWL-650 (PRISM2, minus few newer variants which D-Link messed up to have the
         ACX100 instead)
DWL-G120 (PRISM GT)
DWL-G520 (Atheros AR5212A)
DWL-G650, version A1 (PRISM GT)
DWL-G650, version B1 (Atheros AR5211)
DWL-G650, version B2 (Atheros AR5001)
DWL-AG520 (Atheros AR5212)
DWL-AB650 (Atheros AR5211)
DWL-AG650 (Atheros AR5212)

When looking at the DWL-G650 mess, I could puke again...
Again, the cards mentioned in the listing above will NOT work with this driver
(yet?), in most cases you will need to be able to find a different Linux driver
supporting your card's chipset...
Feel free to send us corrections/additions to this very confusing listing above.

--- STATUS AS OF 040523 ---

Currently this driver for standard ACX100, ACX100 USB and ACX111 cards
still is a bit experimental.
We're still not totally sure about the status of WEP support.
Many situations should work, but it might still not work properly
or fail sometimes.

Also, SMP appears to be problematic (locking issues); if you have SMP,
then turn it off. We will attempt to clean this up as soon as possible.

Furthermore, associating with some access points might still be problematic
due to strict 802.11 compliance checks in their firmware.

Master mode support (aka HostAP) has not really been implemented yet,
but at least it can be configured now.

The non-standard 4x mode (aka "44Mbps") is not supported yet and will need
several driver changes.

Many other things haven't been tested (properly) yet.

Further testing versions can be downloaded from http://lisas.de/~andi/acx100/

A working FreeBSD driver that's derived from our driver can be found at
http://wlan.kewl.org and cvs.kewl.org (thanks, guys, for the cool work!).
There is a free download of the 802.11b spec at
http://standards.ieee.org/getieee802/

--- REQUIREMENTS ---

What to do or have (we will NOT remind you later about any requirements,
since this seeks to list all requirements in full):
* x86 box preferrably (other architectures such as Powerbooks may work since
  they have been tested from time to time, but please report IMMEDIATELY if
  they have any trouble, I'm very interested in that!)
  Users who have other archs may need to remove certain compiler flags
  in src/Makefile which are unsupported by their non-x86 compiler
* most likely a Bus Master capable PCI slot for PCI card versions, slave
  PCI slot won't work (FIXME: is that true?)
* relatively recent Linux kernel 2.4.x (2.5.x/2.6.x experimental)
        with CONFIG_NET_RADIO enabled ("Wireless LAN")
        and CONFIG_NET_WIRELESS, for wireless extensions (iwconfig etc.).
        And Non-SMP (no CONFIG_SMP).
* proper kernel header files / kernel source (packages) installed
        for the exact (*EXACT*!!) kernel you're running! 
* a make package has to be installed
* a gcc package has to be installed
* The /bin/bash shell is required for the start_net/stop_net scripts
* module packages: modutils for Linux 2.4.x, module-init-tools for 2.5.x/2.6.x
* firmware image and radio image for your ACX1xx card
* the package containing iwconfig, iwpriv & Co. needs to be installed
        on your system (on Debian: package wireless-tools)
* the Linux hotplug package is required for automatic setup of CardBus cards
  and for proper ACX100 USB cards operation

What to NOT do:
* believe that this has much to do with PCMCIA. The ACX1xx cards are
  CardBus cards, and thus PCI-based, NOT ISA-based (PCMCIA).
  You probably need the pcmcia-cs package for certain CardBus functions,
  though.

--- FIRMWARE INSTALLATION ---

NOTE: these firmware installation instructions might only apply
to standard ACX100 cards, not necessarily to ACX111 or ACX100 USB cards
(FIXME).

The firmware files are needed to drive the cards' onboard embedded
wireless baseband CPU.
We cannot ship this with our driver, so you will have to get it elsewhere.
There are three options:
a) run "make fetch_firmware"
   This will run the shell script scripts/fetch_firmware, will DOWNLOAD
   driver packages from ACX1xx vendors, extract them and copy required
   firmware files to the firmware/ directory.
   Once run, you are (hopefully!) finished with the firmware section.
b) you have a windows driver installed or have a zip file with all the
   necessary windows files in it (for example D-Link installer).
   This could be for ANY Windows version. All that matters here is that this
   driver package contains relatively recent firmware image files.
c) you have a binary linux driver (not recommended, since these contain
   much older firmware files)

Certain DWL-650+ and 520+ cards and Planet cards use a Maxim radio instead of
the usual RFMD, so these cards will not work with the limited proprietary
linux driver binary's firmware and so a windows firmware with proper
support for this radio type must be used.

FIXME: need to establish proper script support for the fact that the
ACX100 USB firmware should be copied to /usr/share/acx/ACX100_USB.bin

Again, here are your options:

-- Firmware provided by Windows driver --

Easy solution:

wget ftp://ftp.dlink.com/Wireless/dwl520+/Driver/dwl520+_drivers_307.zip
unzip dwl520+_drivers_307.zip
(these may be outdated, you might want to check for newer versions)

cp Win2000/WLANGEN.bin Win2000/WLANGEN.BIN Win2000/RADIO0d.BIN Win2000/RADIO11.BIN firmware/
mv firmware/WLANGEN.bin firmware/WLANGEN.BIN
Ready to roll. :)

Longer background explanation (READ IN CASE OF PROBLEMS!):

The firmware used by the windows driver consists of several files normally
named WLANGEN.BIN, RADIO0d.BIN and RADIO11.BIN which can be found in
the c:\winnt\system32 directory, or in the install archive.
Place these files in the firmware directory, and you are ready to roll.
MAKE SURE THAT THE CASE SeNsItIvItY OF THE FILENAME CHARACTERS IS EXACTLY
AS WRITTEN ABOVE!! Otherwise the driver will NOT find the image files...

Note that earlier versions of the windows driver shipped with both a new
firmware file plus its individual radio files (small firmware plus RFMD
radio file plus Maxim radio file) and old combined versions (one bigger
firmware *including* radio code, which is the old concept).
Here you have a choice, you can either copy the newer individual files over
(which will need to be renamed to the firmware names given above)
or use the old combined file on its own. If for some strange reason you decide
to use the old combined file it must be renamed to "WLANGEN.BIN".
Since our driver WILL attempt to load separate radio modules even with an
old combined firmware (we don't do a version check yet), adding separate
radio files to an old combined firmware WILL cause problems, so better
don't do that...

The firmware files in the recent driver package are:
WLANGEN.BIN - Generic firmware
RADIO0d.BIN - Maxim radio module
RADIO11.BIN - RFMD radio module
RADIO15.BIN - UNKNOWN radio module, e.g. for DrayTek Vigor 520, found at
e.g. ftp://ftp.draytek.com.tw/VIGOR520/Driver/3.99.3.0/driver.zip

The firmware files in earlier packages are:
AIRPLUS.BIN  - Firmware with embedded RFMD module
APLUSMX.BIN  - Firmware with embedded Maxim module
APLUSGEN.BIN - Generic firmware
APLUSRFM.BIN - RFMD radio module
APLUSRMX.BIN - Maxim radio module

Other files:
SMCSN.BIN - combined(?) firmware for SMC2435W

-- Firmware from Linux binary driver (not recommended - too old) --

Several drivers are available on the internet, and they all seem to
work. But since the firmware is embedded in the binary driver, it needs
to be extracted. Place the driver in the firmware directory and make
sure it is called acx_pci.o. Then run 'make extract_firmware', and
you are set. Make sure that no radio modules (RADIO*.BIN) files are
placed in the firmware directory when using a linux firmware, otherwise
the driver will attempt to load and initialise the radio module for your
card again, with unpredictable results (FIXME: need to check against
firmware version on this one, to avoid such trouble; in other words:
which version was the last combined firmware version: please tell us!).
The linux driver already has the radio module embedded in the firmware.
The firmware version which this Linux driver contains is 1.5.0,
as printed during our driver initialisation.


You may tell us about your experiences with various firmware versions,
then we'll add that info to doc/firmware_versions.txt.

--- "NORMAL" DRIVER INSTALLATION ---

This is the usual way to get the driver running on Linux 2.4.x.

You have two choices:

The fast way:
  Just run "make" in the main directory, and your driver will be ready
  in a second. It is located in src/acx_pci.o .
  (NOTE: changed from acx100_pci.o!!)

  In case the build fails, then please make sure that the symbolic link
  /lib/modules/`uname -r`/build exists and points to the matching
  kernel source directory. Now copy /boot/vmlinuz.version.h to
  /lib/modules/`uname -r`/build/include/linux/version.h

The slow way:
  Type "make config.mk" in the main directory to cause some configuration
  settings to be checked.
  Then you type "make driver". This will compile a driver for
  Linux 2.4.x (for 2.5 / 2.6 see below)

To run the driver, you can use the script scripts/start_net (and adapt it).
Oh, and don't forget to have a proper DNS server in /etc/resolv.conf ...
Further system configuration can be found at SYSTEM CUSTOMIZATION below.

"make install" will copy the driver modules to the current kernel's
module directory and will run depmod. If successful, the system should
attempt to auto load the driver on card insert.

In order to get the driver to autoload properly (with a proper
firmware_dir), you could add e.g. to /etc/modprobe.d/acx_wlan
(or /etc/modprobe.conf):
options acx_pci firmware_dir=/absolute/path/to/firmware_files debug=0x0
options acx_usb firmware_dir=/absolute/path/to/firmware_files debug=0x0
and run update-modules (this will be added to "make install" soon).

Once you insert the card, the driver will then load automatically
without error (and will shut down the interface once you eject the card).
Note that the spinlocks inside the driver are still problematic,
so you should avoid ejecting the card in the middle of a data transfer
(OOPS may happen!). A completely safe way to eject is to ifconfig down
the interface, THEN eject the card.

Automatic networking configuration of such a setup can be achieved by
reading the guidelines at
http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/HOTPLUG.txt
However, this seems to still be a bit static.
A more mobile approach might be the ifplugd/waproamd programs
(see below; configuration dependent on stations in reach).

DON'T FORGET that debugging/logging options can be changed in a pretty
powerful way (see "DEBUGGING / LOGGING").
Your hard disk will certainly thank you a lot for having saved it from
the horror of heaps of logs once you got the driver running...
To check out further module parameters and options, please use modinfo
and iwpriv (see also doc/iwpriv.txt).

The module itself can be loaded manually e.g. like:
insmod src/acx_pci.o firmware_dir=firmware

NOTE that firmware_dir has to be given as an absolute path; a relative
path will cause trouble during card reinit operations!! (suspend/resume etc.)

If you want the driver to use eth0 device name instead of wlan0,
then load with an activated use_eth_name option, like:
insmod src/acx_pci.o firmware_dir=firmware use_eth_name=1

For troubleshooting, see below.

--- LINUX 2.6 DRIVER INSTALLATION ---

In order to use the acx100 driver with Linux 2.6 you'll need a complete 2.6
source tree.

In order to build the module outside of a 2.6 kernel tree, just use the
normal method as described for 2.4.x above (you'll most likely need to
compile it as root since it needs write access in your kernel source
directory).

If instead you want to build the module "in-tree" (i.e. not in a separate
acx100 module directory!), you'll have to:

> SOLUTION ONE
Run "make inject" to add the driver to an existing Linux 2.6.x source tree.
By default, the kernel source is assumed to be in /usr/src/linux/, while if
you want to specify another path, you should use the parameter KSRC, so
¨make inject KSRC=[path to your kernel source].

> SOLUTION TWO (this may be outdated)
1. Create a directory drivers/net/wireless/acx in your 2.6 source tree.
2. Copy the files
      - src/Makefile
      - src/*.c
      - include/*.h
   from the acx100 sources into drivers/net/wireless/acx in your 2.6 tree.
3. uncomment line "#EXTRA_CFLAGS += -Idrivers/net/wireless/acx -DWLAN_HOSTIF=WLAN_PCI"
   in Makefile you just copied. (line 142)
4. Add a line reading "obj-m += acx/" to the bottom of
   drivers/net/wireless/Makefile .
5. Then build your kernel as usual, the acx100 driver will be built as module
   (acx_pci.ko). Make sure you have the required 2.6 module userspace
   package (module-init-tools) and enjoy ;-)

> SOLUTION THREE (only for version before 0.2.0pre8)
Other 2.6.x kernel patches can be found at http://luca.pca.it/projects/acx100/

--- USAGE HINTS ---

Want to use driver as BUILTIN kernel driver, but then driver fails to know
where the firmware files are? Use kernel boot parameter acx_firmware_dir=XXX.

Card insertion driver autoloading? You need to configure PCI hotplug layer,
*NOT* pcmcia-cs layer!

Need to change MAC address? Use ifconfig wlan0 hw ether 112233445566
Setting will only get updated when not associated: needs reinit of card parts.
And it doesn't work quite right yet, communication is distorted :-\
(maybe the card firmware even keeps the MAC address of the EEPROM or so...)

Wireless traffic monitoring with Kismet? Set card type Orinoco in kismet.conf
(in case of an older Kismet release which didn't know the acx100 type yet).
Oh, and also make sure to run "iwpriv wlan0 monitor 2 4" to enable.

Wired-Wireless bridging? Driver would perhaps need to support WDS
(whatever that is). For now, proxy ARP should do:
http://www.hazard.maks.net/parprouted/

--- DEBUGGING / LOGGING ---

Debug/log levels can be adapted by setting the module's "debug" load parameter
and/or via the "iwpriv set_debug" command and/or the default log value
(variable "debug") in src/acx100.c.
A good default value after having managed to get the driver to run would be
0xb (thus using L_STD|L_INIT|L_ASSOC debug channels, see include/acx100.h).

Example:
insmod src/acx_pci.o ... debug=0xffff
iwpriv wlan0 set_debug 0xffff

-- log file --

Log output of the driver gets written to the file which the
KERN_WARNING channel gets written to (somewhere in /var/log/).
The exact file name used for this log file is configured in the syslog
configuration file which is called /etc/sysklogd.conf or similar.

-- log console --

A log console (e.g. /dev/tty8) may be configured in /etc/syslog*.conf
(don't forget to restart syslogd).
Change to the logging console (Ctrl-Alt-F8) to view the kernel log messages
instantly (useful in case of driver crash debugging).

--- TROUBLESHOOTING / WORKAROUNDS ---

Don't forget to set the driver debug/log level (see above) to 0xffff in case
normal message logging is insufficient to resolve your card problem!
Also, cat /proc/driver/acx* might give some clues...

-- Driver build problems --

If the driver compile or loading keeps failing, then it might be caused
by a module version conflict of your current kernel, such as:

./../src/acx_pci.o: unresolved symbol unregister_netdev_Rdbdb76d4

Consider completely recompiling the kernel (make sure to keep any old
.config file with previous config settings!), then removing the WHOLE
/lib/modules/KERNELVERSION/ directory tree, then reinstalling this kernel and
rebooting. Hopefully the driver compiling works then.

Also, I hope you haven't downloaded the driver via Windows CVS (since it
may insert bogus end-of-line chars).
  
-- Driver init failure --

If you get "Invalid module format" during insmod, then it's probably a
gcc version difference (see syslog) and you should make sure to compile
the driver with the same gcc version that you used for compiling the kernel.

- CardBus specific -
You need to make sure you're having CardBus support (otherwise you'll have
strange PCI init failures), and it should be kernel CardBus support, not
pcmcia-cs CardBus modules! (yenta socket module instead of e.g. i82365 module)
On SUSE: "kernel" type instead of "external".
Thinkpad notebook? Make sure your CardBus feature is enabled in the
configuration utility...
If your card gets recognized as "Anonymous Memory" (i.e. gets inserted,
but doesn't get recognized as a CardBus card), then try to use
further memory and port areas in /etc/pcmcia/config.opts (restart
pcmcia-cs). Also, try *restricting* the areas it probes instead: sometimes it
fails to detect a card if there are large amounts of ranges to be probed.
And of course also trying the other CardBus slot in case you are lucky
enough to have 2 slots sometimes actually helped to fix IRQ problems...
With certain Toshiba notebooks you need to go into the system bios
and set the PCIC *not* to be "auto", set to the other option.

- General -
If the system detects your card, but the driver is unable to initialize the
card due to the card having IDs 0xffff etc., then play with Linux boot
parameters, specifically the "pci=XXXX" flags, and most specifically,
"pci=assign-busses", since this managed to fix it for several persons
(DWL-650+, Vigor520).
Please tell us if this managed to resolve some issue with a particular card!
Use tools like "cardctl info", "lspci -v", "dump_cis".
Also, make sure to shuffle cards in different PCI slots!! The ACX1xx probably
needs PCI bus mastering support, and some motherboards either don't support it
at all or not in certain crippled PCI slots.
And of course there are also cases where it is PCI interrupt sharing which
causes init trouble. A log message like "PCI: Sharing IRQ 3 with 00:01.1"
indicates that sharing is happening, which might cause trouble.
Using APM instead of ACPI has also been reported several times as fixing
init problems, so reconfigure your kernel to use the other one...
(kernel boot parameter "pci=noacpi" might be useful here, and it also
helped several times!)
Oh, and last but not least, always make sure to get the latest BIOS for your
computer - that also helped in some cases of broken power management code or
resource allocation!

-- Driver locked up the box --
Umm... ouch!
First, use newest driver version.
Then please configure a log console (see "DEBUGGING / LOGGING").
Run
sleep 10 && insmod acx_pci ......
Then change to the log console, wait 10 seconds and write down the crash dump.
Then please file a bug report. Thanks!

This could also happen due to some PCI bus incompatibility (the ACX100
states a PCI2.2 requirement!!). If you happen to have a SB Live! card and
lose sound or have crashes when using the ACX100 card, then try
loading the ACX100 card driver BEFORE loading the SB Live! (this managed
to fix sound for one person)
Hmm, OTOH someone else reported that inserting the ACX100 card AFTER
bootup manages to fix it. So simply try swapping the sound/network
module init sequence.
Also, using an SB Live! with ACX100 may result in crashes and data corruption.

-- Wireless config failure --

If you get log messages like
Buffer for request 8B0B too small (0<564)
or other strange/erratic wireless config behaviour, then make damn sure that
your wireless-tools version is correct! There are tons of possibilities
for version conflicts!

-- Network failure --
First, make absolutely sure you're using correct settings for
association to the wireless network!
It's of no use to try to associate to a set of access points using
Ad-Hoc mode, or maybe the other way around (to use Managed mode to
associate with a card set to Peer).
Further, the ESSID is CaSe SEnsITivE!

Then read the file containing the driver log (see "DEBUGGING / LOGGING").

Make sure that network association is working properly!
(all steps that get listed from STARTED, SCANNING, WAIT_AUTH,
AUTHENTICATED to ASSOCIATED finish successfully)
Also make sure your peer AP has reliable Beacon period settings
(100ms is the standard value which our driver always detects during scan,
longer periods may cause trouble).

Also, check whether you actually use the newest or a working firmware version.
In some cases it's actually not this driver but the firmware which is
misbehaving...

If you connect to an AP with hidden ESSID ("") and you happen to have
several APs with hidden ESSID in your environment, then you need to also
specify the AP MAC address in order to make sure that the *single attempt*
we're making connects to the AP you want...


If you are still having trouble, then make sure that you didn't get an iwconfig
version incompatibility warning. This can mess up terribly many settings :-((
Get new wireless-tools then...

We tried to make the driver log as dumbed down as possible to make sure
even casual wireless users are able to follow the network association steps
towards the final successful association.

Usual power levels for a connection are (at least for my PheeNet WL-0022
CardBus, other people WILL have better or worse results!):
Signal level 86/100 (extremely good, at least to my PheeNet AP with DWL-900AP+
                     firmware; directly neighbouring the AP)
Signal level 29/100 (anything less: connection lost @22Mbps)
Signal level 26/100 (anything less: connection lost @11Mbps)
Signal level 21/100 (anything less: connection lost @1Mbps)
Noise level 0/100 (anything more can be problematic, > 10 is deadly)
Link Quality == reverse of Noise level

Note that these signal levels are *NOT* expressed in dBm, instead it's a
percentage value (of course, since xx/100 is percentage) which as closely as
possible matches values of the current Windows driver.
I still hope that we'll be able to calibrate our driver eventually to show dBm
values :-\
Note that signal levels in Ad-Hoc mode are being displayed relative to the station
which answered during our initial scanning period, so the signal level source
(and thus the average level!!) might change with every new association.

Also try other channel values to reduce interference by cordless phones,
microwaves etc.

If you keep getting Tx errors, also try setting other values for
"iwconfig sens" (e.g. 92, useful values are between 30 to 100 and
between 160 and 200).

When trying to use NFS, use options 'rsize=1024,wsize=1024' in /etc/fstab .


If you experience complete traffic lockups after some random time,
then don't use hdparm -u1, since it may lockup/delay driver IRQ
operation for some yet unknown reason.

Some connection problems might also be caused by the Access Point using a
problematic antenna configuration setting (e.g. "internal" instead of
"external" or so).

If you still have trouble getting a connection, or if the connection is
problematic, then try
http://www.houseofcraig.net/acx100_howto.php
or visit our Wiki HOWTO/troubleshooting pages for more info.

And if that still doesn't give you the info you need,
then consider NOT posting a request on the Forum or writing to the mailing
lists, since we cannot track these properly.
Instead, post a Tracker item at one of Bugs, Support Requests, Feature
Requests. This way development will be much more organized, with proper
status and processing assigned to each request, and hopefully nothing
falling through the cracks. And please consider NOT posting anonymously,
since this severely degrades tracking quality.

****************************************
A useful report would include:
- the acx_proc.txt file created via
    "cat /proc/driver/acx* > /tmp/acx_proc.txt"
- in case you're experiencing connection issues or similar:
    the output log files of the debug=XXXX parameter (see "DEBUGGING / LOGGING")
****************************************

Thanks for listening!

--- BUGS / SHORTCOMINGS / PATCHES ---

- will not work on SMP multi-processor kernels yet
           (some problems, maybe even crashes). Working to fix that.
- power management (suspend/resume) handlers are not finished yet
- no automatic rate adaptation yet
           (setting rate to 22M will prevent communication with 11M peers)
           We'll have to implement auto rate adaptation properly soon.
- many advanced features are not implemented yet

For current tasks, please read TODO (or grep driver for FIXME and TODO).

In case of bugs that didn't exist in previous versions,
PLEASE do regression testing via CVS:
http://www.winehq.org/site/docs/wine-devel/cvs-regression
(remember: WE are doing the driver, so it's YOUR responsibility to get any
problems fixed that might happen in between...;)

If you manage to fix or implement something, then please immediately
send patches for inclusion to the acx100-devel@lists.sf.net mailing list.

************************* !!!!!!!!!!!!!!!!!!!!!  *************************
NOTE that by sending us patches, you implicitly accept that we also publish
them in BSD licensed form eventually, since we want to keep this driver
functionality usable by BSD systems and we assume that you've read this note
about patch submission in this main README file that everybody is
supposed to read before making use of our project (and projects in general!).
If you don't want to accept this implicit licensing, then please make
sure to let us know which code parts are not supposed to be used by BSD
systems. Thanks!
************************* !!!!!!!!!!!!!!!!!!!!!  *************************

--- SYSTEM CUSTOMIZATION ---

Again, no automatic system installation is provided, since the various Linux
distributions often differ in their exact network configuration methods
and it's really not our job to care about maybe 5 to 10 different
distribution scripts (at least not now as long as our driver is
especially experimental).
Thus maybe simply adapt and use our scripts/start_net script. Or add
that script as a properly executed init script in /etc/[rc.d]/init.d/
(use e.g. /etc/init.d/skeleton as an example)
Then create e.g. runlevel 2 symlinks ("ln -s") from K* and S* scripts in e.g.
/etc/rc2.d/ to your init script in /etc/init.d/ and it should hopefully
get loaded automatically on system bootup.

module autoloading configuration (e.g. in /etc/modprobe.conf or
/etc/modules.conf) could be:

options acx_pci firmware_dir=/home/ivor/cvs/acx100-0_1a-rc1/firmware
alias wlan0 acx_pci

USING WAPROAMD
The waproamd is "a roaming daemon for wireless IEEE 802.11 NICs supporting
the Linux wireless extensions". 
1. install waproamd (http://0pointer.de/lennart/projects/waproamd/) [debian package available] so it will be started before you insert the pcmcia wlan card;
2. put your pcmcia card in;
4. waproamd shall make all work for you.
3. if driver was not loaded or loaded with errors do from console
Remove acx_driver if loaded with errors
"rmmod acx_pci"
Load acx_pci driver (change paths according to Your settings. The below is for acx100 module build in 2.6.x kernel tree. [This is a one line command]
"insmod /lib/modules/`uname -r`/kernel/drivers/net/wireless/acx100/acx_pci.ko use_eth_name=1 debug=0x01 firmware_dir=/lib/modules/acx100_fmwe/"
The waproamd daemon has to look for available access points and set the eth1 nic properly.
4. And finally try to use dhcp 
"dhclient eth1"
or set ifconfig manually. 

--- AND FINALLY... ---

Let me mention that we REALLY dislike the way very stupid hardware vendors
name their cards containing DIFFERENT chipsets!!

One of these vendors is SpeedStream/Siemens: a card that uses the same
name "SS1021" is available in both Orinoco chip and ACX100 chip versions.

USRobotics also just started to enjoy these despicable acts:
the USR2210 usually has the ACX100, however newer versions with UNCHANGED
naming (e.g. at tigerdirect.com) contain a newer incompatible 802.11g
TI chipset.

But the worst offender is D-Link: they have "DWL-650" and "DWL-650+".
"DWL-650+" is simply an improved version of the "DWL-650", right?
WRONG!
The standard versions use Prism2.5, whereas the "+" versions use ACX100
chipset. Good luck in finding a (correct) driver!!
And it's even WORSE: I just found out that there is some newer
version of the "DWL-650" out that also contains the ACX100
(it uses the same hardware as the "+" versions).
Not to mention that D-Link now uses the DWL*650* naming for about 6 or 7
different products!
This BRAINDEAD STUPIDITY in device naming easily entitles D-Link
for the "Most Braindead Hardware Vendor 2003" award. And of course
they were also talking about developing another Linux driver for some time,
without any results (although I guess that's because they wanted to
develop it, but were not allowed to, unfortunately, so it's understandable).

IF you dare to release cards with a different incompatible chipset
that doesn't even have proper driver support for a popular alternative OS,
then AT LEAST change the card name in order to let people know and discern
which hardware to avoid like the plague, for heaven's sake!
This is such a <CENSORED>, I could <OUCH, CENSORED!>...

Also, we just learned that D-Link tech support can be very clueless, too:
one guy, after having been advised that his DWL-120+ uses an Atmel
chipset, spent considerable time trying to get this card to work with an
incompatible Linux driver (it's the DWL-120 which uses an Atmel chip -
the DWL-120+ is using an ACX100 in USB mode!).
This proves that D-Link really deserves the award above,
and it also shows that one should avoid D-Link like the plague from now on
(at least until they get rid of their stupid product naming habits),
since they don't seem to know or care about their very own products.

Finally, let me mention that we also really dislike the way how
Texas Instruments handles Linux driver support. It's a really shameful
pity, with delays to be measured in years versus the Windows driver
support, and with poor and buggy binary driver support.
All in all our team would be very grateful to receive proper
development support and cooperation from TI in order to create
proper Linux drivers. That would be The Good Way to do it...
(although admittedly that would still only be the second-best way to do it,
with the best way being to have paid company developers work on a
well-working OSS driver, of course)
After all it's the hardware VENDOR that's earning money via OUR, the
customers', payment, so it should be the damn responsibility of the
hardware vendor to ensure good driver support (if by no other means
than providing sufficient specs to OSS developers), not the other way around!
Just imagine the weird looks of thousands and thousands of Linux users
when they discovered the lack of support for the product that they just
shelled out considerable amounts of money for...

Have fun!

The ACX100 OSS driver project team :-)
http://acx100.sourceforge.net