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

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

Please NEVER consider using the NDIS driver loader cludge instead of our driver.
For bazillions of reasons against it, please see
http://acx100.sourceforge.net/ndis_cludge.html

--- CARD COMPATIBILITY (aka "OUCH!!") ---

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 -- successful firmware loading support
for USB is in the driver now and receiving works, but transmitting doesn't
- feel free to work on this support).
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!).

Note that any Texas Instruments chips OTHER than the ACX100 (which is
also known as TNETW1100) are not supported by this driver (yet).
These chips are e.g. 802.11g capable, and they may be named TNETW1130/1230
(ACX111).
Initial ACX111 support is in the driver, but it's still a bit far from working,
due to many changes compared to the ACX100.

Also, due to similar card naming confusion (for further information, see
bottom), people keep thinking certain cards they own work with this
driver. Cards that are *NOT* based on ACX100 chipset (as opposed to
the stupidly similarly named ACX100 versions DWL-120+, DWL-520+ and DWL-650+,
which *do* have ACX100) 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)
DWL-G520+ (TNETW1130: not fully supported yet, but it's being worked on!)
DWL-G650+ (TNETW1130)

When looking at the DWL-G650 mess, I could puke again...
Again, the card mentioned in the listing above will NOT work with this driver,
you will hopefully 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 031101 ---

Currently this driver still is a relatively experimental release only.
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.

HostAP support has not been implemented yet, but it's definitely possible.

4x mode (aka "44Mbps") is NOT supported yet and will need several
driver changes.

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

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):
* 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
* firmware image and radio image for your ACX100 card
* the package containing iwconfig, iwpriv & Co. needs to be installed
	on your system (on Debian: package wireless-tools)
* the Linux hotplug package is useful (required??) for CardBus cards

What to NOT do:
* download the driver via Windows CVS (may insert bogus end-of-line chars)
* believe that this has much to do with PCMCIA. The ACX100 cards are
  CardBus cards, and thus PCI-based, NOT ISA-based (PCMCIA).
  You probably need the pcmcia-cs package for certain CardBus functions,
  though.

About the firmware files:
We cannot ship this with our driver, so you will have to get it elsewhere.
There are two options:
a) 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.
b) 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.

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 acx100_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 on
our Wiki page FirmwareExperiences.

--- "NORMAL" 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/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" 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)

No install option has yet been provided (because the driver is still a bit
experimental anyway :)

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.

DON'T FORGET that debugging/logging options can be changed in a pretty
powerful way by setting the module's "debug" parameter and/or its
preinitialisation value in acx100.c and/or via the iwpriv set_debug setting.
A good default value after having managed to get the driver to run would be
0xb (L_STD|L_INIT|L_ASSOC debug channels). 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.

The module itself can be loaded e.g. like:
insmod src/acx100_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!!

If you want the driver to use eth0 device name instead of wlan0,
then e.g. load as:
insmod src/acx100_pci.o firmware_dir=firmware use_eth_name=1

For troubleshooting, see below.

--- LINUX 2.6 INSTALLATION ---

In order to use the acx100 driver with Linux 2.6 you'll need a complete 2.6
source tree and have to build the module "in-tree". You'll have to:

1. Create a directory drivers/net/wireless/acx100 in your 2.6 source tree.
2. Copy the files
      - src/Makefile
      - src/*.c
      - include/*.h
   from the acx100 sources into drivers/net/wireless/acx100 in your 2.6 tree.
3. Add a line reading "obj-m += acx100/" to the bottom of
   drivers/net/wireless/Makefile .
4. Then build your kernel as usual, the acx100 driver will be built as module
   (acx100_pci.ko). Make sure you have the required 2.6 module userspace
   package (module-init-tools) and enjoy ;-)

--- USAGE HINTS ---

iwpriv commands? See doc/iwpriv.txt

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

Wireless traffic monitoring with Kismet? Set card type Orinoco in kismet.conf.
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/

--- 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/acx100* 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/acx100_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.

-- Driver init failure --

- 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 helps to fix IRQ problems...

- 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 one person (DWL-650+).
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 ACX100 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 as fixing init problems, so
reconfigure your kernel to use the other one...

-- Driver locked up the box --
Umm... ouch!
First, use newest driver version.
Then please configure a logging console (e.g. /dev/tty8) in
/etc/syslog*.conf, restart syslogd, then do:
sleep 10 && insmod acx100_pci ......
Then change to the logging console (Ctrl-Alt-F8), 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.

-- 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 (the file where
the KERN_WARNING channel gets written to, somewhere in /var/log),
as given in the syslog configuration file which is called /etc/sysklogd.conf
or similar.
debug level can be changed by doing e.g.
iwpriv wlan0 set_debug 0xffff

Make sure that network association is working properly!
(all steps that get listed from STARTED, SCANNING, WAIT_AUTH,
AUTHENTICATED to ASSOCIATED finish successfully)

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

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

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


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 acx100_log.txt file created via
    "cat /proc/driver/acx100* > /tmp/acx100_log.txt"
- in case you're experiencing connection issues or similar:
    the output log files of the debug=XXXX parameter (see above)
****************************************

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.

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