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

An alternate, most likely infinitely much better, more detailed guide can be
found at http://www.houseofcraig.net/acx100_howto.php
Regardless of this guide, this README contains a very large amount of important
first-level driver info, so I'd definitely advise to read it as much as possible.

!!!!! MANDATORY WARNINGS !!!!!

I just learned that the WRT54G router (non-ACX1xx chipset) has trouble with its
radio when running with higher than usual Tx power (70-100mW or so)
which is possible using incredibly useful custom Linux firmwares
(e.g. the Sveasoft ones), meaning that people end up with defective radios
sometimes after 3 months even, if they choose irresponsibly high
Tx power levels!!
Since this driver can drive ACX1xx cards to use up to 100mW of power,
I really don't know how long the radio would stand that.
Thus it'd be useful to not use full output power if you can avoid it!!
Note that so far I haven't had any defects during constantly using
maximum power (our "20dBm" setting) for many months now, so it MIGHT
be safe. However you might have different hardware which doesn't take that
so easy...
(BTW: my *builtin* mini-PCI card disables its radio every few hours,
and that might be linked to overheating protection or so...)
Thus I adjusted all driver files to use a hopefully safe 18dBm per default
(which is the firmware default, too).
Please inform us immediately if you suspect a dead radio resulting from
prolonged use of overly large Tx power, we'd like to know that immediately!!!!!

UPDATE: I found out that after a large amount of use (primary development card!),
one SMD capacitor of the mini-PCI card in my notebook leaked. This is probably
due to a terrible heat situation in modern notebooks. Replaced the SMD
capacitor with a hopefully equivalent one, seems to work fine.
This could have been aggravated by the driver always recalibrating the radio
on Tx error, which might have allowed the radio to operate beyond the critical
high temperature limit...
Since our driver now does the next recalibration several minutes later only,
this should be more than enough time to notice that the card isn't working under
good conditions.
CONCLUSION: better make sure that the card isn't excessively hot in case it
stops working temporarily. It might damage the hardware after some time
otherwise...

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

Card 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...
Hmm, no, after some more time I cannot say this for certain any more (no
further defects reported to me).


Please don't use 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
(for a start: our driver now supports AMD64, PowerPC, MIPS and of course x86
-- now please try to do that with NDIS loader "solutions", ok?)
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" sorely 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...
If you absolutely don't want to miss out on NDIS loader functionality,
then I'd suggest trying the free alternative NDIS Loader instead,
at http://ndisloader.sourceforge.net (FIXME right URL? No internet at home... ;).
This way at least you won't be telling a company with your money
(aka: the most important way to "vote") that you think
that "doing a blatant Windows binary driver usage ripoff is the right way that
Linux wireless 'support' should be developed".

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 Compact Flash implementations,
which are very rare). USB support exists for both 2.6.x and 2.4.x,
however it may be not completely "stable" yet, and Linux 2.4.x USB stack
is buggy (both uhci and usb-uhci; ohci and ehci should be ok, though),
so better use 2.6.x for USB! [041203]

Determining whether your wireless card is supported by this driver can
be done by running "lspci". This should give you an idea whether it should
be ok or not.

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
(trying previous versions of the driver is very important as well!).

Other Texas Instruments chips which are e.g. 802.11g capable and are named
TNETW1130/1230 (ACX111) started to actually be supported in a useful way
by this driver some time ago only, so due to different hardware
implementations some ACX111 card designs might still not be working yet,
even at this time [041203].

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... (try Google "[CHIPSET] Linux")
Feel free to send us corrections/additions to this very confusing listing above.

=== STATUS AS OF 050407 ===

Status Matrix:

		ACX100			ACX100 USB		ACX111
Rates		1/2/5.5/11/22 (+auto)	1/2/5.5/11/22		all up to 54Mb (+auto)
5GHz		--			--			NIY (any hardware?)
Ad-Hoc		* (WEP64*/128*/256*)	* (WEP64?/128*/256?)	* (WEP64*/128*/256?)
Managed		* (WEP64*/128*/256*)	* (WEP64?/128*/256?)	* (WEP64?/128?/256?)
Auto mode	- (DISABLED recently!!)	- (dito)		- (dito)
Master		?			?			?
Change Tx power	* (hardware)		- (may do via FW only)	-
Config antennas	* (currently via FW)	?			-
Sensitivity	* (hardware)		- (no go since USB?)	* (various F/W settings)

Currently this driver for standard ACX100, ACX100 USB and ACX111 cards
still is a bit experimental.
There's no development roadmap since I don't have much time and thus I cannot
say accurately enough when features will be implemented. You might want
to look at the TODO file for things planned in the future (in order of
importance).

We're still not totally sure about the status of WEP support:
ACX100: Many situations should work, but it might still not work properly
or fail sometimes.
ACX111: WEP **FINALLY** working (thanks HEAPS to Luis Padilla Visdomine for
magically pin-pointing the very hard to find issue - you're our hero!!).
If you need encryption that is much more secure than WEP, you might want to use projects like OpenVPN or others.

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.
Please report any trouble here!

Furthermore, associating with some access points might still be problematic
due to strict 802.11 compliance checks in their firmware (which we fail
to meet, of course). This should also be better now thanks to the very
astonishing work done by Denis Vlasenko. [050420]

Master mode support (aka HostAP) has not been implemented fully yet.
It looks like it will be working very soon, though. [050420]

The non-standard 4x (4X) mode (aka "44Mbps") is not supported yet and will need
several driver changes. Don't hold your breath, this is really low priority.
You might want to disable 4x mode support in your AP, since it is suspected
to cause problems sometimes.

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
  (minimum reported working so far: ACX100 - 486@100MHz, 16MB)
  Other architectures:
  AMD64 should work now.
  PPC (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 of architectures other than x86 may need to remove certain compiler
  flags in src/Makefile which are unsupported by their non-x86 compiler (e.g. -march=i586)
* most likely a Bus Master capable PCI slot for PCI card versions, slave
  PCI slot won't work (FIXME: is that true? Please report!)
* relatively recent Linux kernel 2.6.x or 2.4.x (>= 2.4.18 preferred)
	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! 
  It is recommended that this kernel is new enough to support wireless
  extensions version WIRELESS_EXT > 13
* 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: module-init-tools for 2.5.x/2.6.x, modutils for Linux 2.4.x
* firmware image and (sometimes) radio image for your ACX1xx card
  (these need to be uploaded into the card RAM on every driver initialization)
* 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, and in case of a 2.6.x kernel
  optionally for firmware binary hotplug loading (this will require a loaded
  firmware_class.ko module as well)

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.
* believe that this driver uses the hotplug package's firmware upload
  functionality. Right now it uses its completely separate and thus
  Linux 2.4.x (which doesn't support this firmware upload)
  compatible mechanism!


=== FIRMWARE INSTALLATION ===

NOTE that there are varying degrees of firmware stability and/or compatibility
with what *our* driver expects the firmware to do.
Thus you might want to use a different firmware version (the version number
can be found in the driver log) in case of problems getting the card to work
(reliably).

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

-- Firmware for ACX100 non-USB cards --

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.

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

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

-- Firmware for ACX100 USB cards (D-Link DWL-120+) --

Read the ACX100 instructions above, but keep in mind that they may be wrong
since you're using a USB card with USB specific ACX100 firmware.
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

-- Firmware for ACX111 cards --

Read the ACX100 instructions above, but keep in mind that they may be wrong
since you're using an ACX111 card with ACX111 firmware.
NOTE: For ACX111 cards even recently there are both a combined firmware
(TIACX111.BIN or FwRad16.bin) and a non-combined firmware (FW1130.BIN?)
available (see further below).
Occasionally a firmware is also called GPLUS.BIN originally.
You need to rename it to TIACX111.BIN in this case (especially in newer
driver versions, which limited possible filename alternatives!!).
Note that D-Link makes a driver download distinction between the DWL-G650+ Rev. Ax and Bx: they are both ACX111, but contain different firmware images!
This could mean that there might be hardware differences between various ACX111
implementations, and thus you might need to use a specific firmware for your
particular card.

You need to make sure our driver has both the main firmware functionality plus
radio functionality available, otherwise you won't transmit anything!
Either by using a base firmware plus additional radio image file, or by using
a combined firmware which already includes radio functionality.
For non-radio firmwares you NEED the additional radio module, with radio
firmwares you MUST NOT have the driver load the radio module.
ACX111 cards usually have radio types 0x16 or 0x17 (see log message).

=== 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 below (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/

=== LINUX 2.4 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.

The firmware files can be copied to /usr/share/acx/ (the driver's default
firmware directory) if you don't want to specify the firmware_dir= parameter
on module loading above.

In order to get the driver to autoload properly, 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 (on Debian; not sure with other systems) 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.

=== USAGE HINTS ===

A VERY GOOD IDEA is to do a
cat /proc/driver/acx_wlan0_eeprom > ~/acx_card_XXX_eeprom_image.log
as soon as you get the driver running, and to store this file containing
the data of the card's *configuration* settings EEPROM in a very safe place.
In case the card somehow managed to trash its EEPROM (or EEPROM weakness),
you would thus at least be able to restore the EEPROM (once we develop
an EEPROM restore option which doesn't exist yet...).
This would also help in case Windows trashed the card EEPROM somehow.
I already managed to resurrect some DROP DEAD cable network card's EEPROM
(most likely trashed by XP driver) once, and from that time on
everybody around me called me a wizard ;-)
Needless to say this is an even better idea once we actually implement
modifying the card config EEPROM to allow for more useful settings ;-)

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!

Use separate driver instances for multiple cards? Enable include/acx_config.h
SEPARATE_DRIVER_INSTANCES config setting (Linux 2.4.x only for now!!).
insmod acx_pci -o acx100_pci.wlan0 card=1 interface=wlan0
will then load a separate driver *only* for the first card in your system,
giving it the wlan0 interface.

Need to change MAC address? Use ifconfig wlan0 hw ether 112233445566
NOTE: make sure card interface is down! (driver will only update MAC
when not associated: needs reinit of card parts)
Also, this will only work in case your AP's MAC filter doesn't deny your new
MAC!
BTW, a nice tool for this might be the "GNU MAC Changer".

Wireless traffic monitoring (promiscuous mode) with Kismet? Set card type
Orinoco in kismet.conf (in case of an older Kismet release which didn't know
the acx100 type yet).
A kismet cmdline example would be "kismet -c acx100,wlan0,acx100 -- -q".
Oh, and also make sure to run "iwpriv wlan0 monitor 2 4" to enable (if required).

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/

Trying to use NFS? use options 'rsize=1024,wsize=1024' in /etc/fstab .

=== DEBUGGING / LOGGING ===

Debug/log levels can be adapted by setting the module's "debug" load parameter
and/or via the "iwpriv SetDebug" 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 SetDebug 0xffff

If you want to prevent log messages from flooding your tty,
then use setterm -msg or setterm -msglevel.

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

On some systems (e.g. Conectiva distribution), it may be required
to run a "make prepare-all" in the Linux source tree before building
the driver...
  
Also, I hope you haven't downloaded the driver via Windows CVS (since it
may insert bogus end-of-line chars).

-- Driver init failure (sorted according to init progress) --

If you get the message

insmod: error inserting './../src/acx_pci.ko': -1 Invalid module format
Error while inserting module! Bailing...

during insmod, then it's probably a binary incompatibility (gcc version
or CPU architecture or (non-)register calling convention or kernel version
-- see syslog for evidence!!)
and you should make sure to compile the driver with the same build settings
that you used for compiling the kernel.
Running "depmod -ae" might actually fix the problem already, though.

insmod message "Unknown symbol in module" and then in syslog
"acx_pci: Unknown symbol release_firmware"?
Load the firmware_class.ko module.

- 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).
If a PCI memory region cannot be reserved, then you may need to tell the
CardBus driver to use a different memory region, as reported in one case.
Please tell us if these 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!

If you have trouble with the ACX100 mini-PCI card in your notebook (i.e.
the notebook restarts immediately after suspending), then you have a
notebook with BIOS troubles as well (the BIOS needs to handle the PME#
pin activity properly). Workaround: disconnect/hide the PME# signal
on the card (pin 34, see mini-PCI spec).

If your firmware upload fails due to upload corruption (see log!) or
there is some other I/O port communication weirdness during driver use
such as reading back strange data, then this could indicate I/O timing issues:
Set ACX_IO_WIDTH=16 in the Makefile, then recompile, to use 16bit I/O access
instead of slightly problematic but faster 32bit access.
The reason why 32bit access causes problems with some cards on some
machines (it might be tied to the CardBus controller) is not known yet.
If you have any useful additional information, please report.

If you get messages similar to
"Failed to allocate shared memory for Rx buffer...", then please report.
This shouldn't happen any more, unless you have very little memory,
in which case buying more RAM (which is always VERY important in Linux!) may
help.

A huge delay when loading the firmware files means that the driver is
trying to load the firmware via Linux 2.6.x hotplug firmware loader,
but the firmware file isn't where it expects it, so after a long timeout
the driver can continue with the old firmware upload method.

-- Driver locked up the box (OOPS etc.) --
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 an ACX card (both 802.11b *and* 802.11g
chipsets are affected, according to reports!), then try loading the ACX1xx
driver BEFORE loading the SB Live! (this managed to fix sound for one person)
Hmm, OTOH someone else reported that inserting the WLAN card AFTER
bootup manages to fix it. So simply try swapping the sound/network
module init sequence.
Also, using an SB Live! with ACX1xx may result in crashes and data corruption.
You might choose to avoid any potential issues by getting rid of either
the ACX card (much preferred; reason: TI support policy...) or the SB Live!

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

A message like
Warning: Driver for device wlan0 has been compiled with version 16
of Wireless Extension, while this program is using version 15.
Some things may be broken...
also means that you should consider upgrading your wireless-tools,
since it's a version that doesn't match the one of your currently running
kernel (or acx100 build kernel).

-- Network failure --
First, did you ifup the card? (ifconfig wlan0 up)
Without an activated interface there won't be any net connection at all,
since the wireless part (and much more) of the card will be deactivated...
Also, 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).
NOTE that we recently abandoned the Auto mode setting; you need to do an
explicit configuration by specifying Managed or Ad-Hoc mode, otherwise
the driver won't do anything (policy: "don't connect to random networks
if the user isn't sure what he wants").
Further, the ESSID is CaSe SEnsITivE!
Since the driver is currently doing passive scan only, your peer station HAS
to be configured to send Beacon frames (100ms Beacon period works best).

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

Make sure that network association is working properly!
(all steps that get listed in the log 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).

Maybe basic or operational rate set is set incorrectly, so association
to an AP fails.
Try to fix it, e.g. something like iwpriv wlan0 SetRates "1,2 1,2,5,11".
This is also required to let Ad-Hoc Beacons from acx111 cards get recognized
by 11Mbps cards, since otherwise the Beacon Tx speed will exceed 11Mbps!
(will be done automatically in a future driver version)

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 get some "link failed" message or similar, try using
MII_NOT_SUPPORTED=yes in your /etc/sysconfig/network-scripts/ifcfg-wlan0
or similar file.

Disable packet fragmentation on your AP, since our driver doesn't
support Rx and Tx (de-)fragmentation yet, so this may cause problems.

Disable any 4X mode feature on your 22Mbps AP, since our driver doesn't support
4X mode yet and 4X mode is known to cause problems sometimes.

Using IPv6? Make sure to configure an MTU >= 1280, otherwise setting
the address will fail with an obscure "not enough buffer space" kernel error!

If your transfer speed is very low in auto rate mode, then make sure to use
a maximum rate that's compatible with the maximum rate of your peer
(non-auto-rate mode wouldn't get any connection in that case, BTW...).

If traffic is problematic in case other peers are active, then fiddling with
iwconfig rts might help.

Multicast not working? The driver is currently not fully handling multicast.
See https://sourceforge.net/forum/message.php?msg_id=2361212 for discussion
and (semi-)solutions.

IRQ lockup (no more IRQs from card) after some time? Try booting with or
without ACPI enabled, has been reported once to fix it.

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 (although I guess
it's not as closely matching as we thought!).
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.
UPDATE: changed driver to update level from every packet received, no matter
which peer.

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 and 100 and
between 160 and 200). Most useful range is 85 to 91 (91 best).
In case of Tx error 0x20, use iwconfig retry (set both values!).


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. Please try to not post anonymously,
since this severely degrades tracking quality. Thanks!

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

- might not work on SMP multi-processor kernels sometimes
           (some problems, maybe even crashes). Reported to work, currently
- power management (suspend/resume) handlers are not completely stable yet
- several 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

ACX111 card support can be changed to use 32 ring buffers instead of 16
(we are using 16 since 32 often fails to allocate enough memory!) by
changing the RXBUFFERCOUNT_ACX111/TXBUFFERCOUNT_ACX111 defines to 32.

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 terrible misdeeds:
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.

Sitecom recently also joined the devilish party with their "WL-120" (ACX111)
and "WL-120 v2" (Harris) cards. Plus, they had GPL non-compliance issues with
some of their products and were ultimately told by the court to obey it properly.

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 rather clueless, too:
one guy, after having been ill-advised by D-Link support 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!).

However, all things considered, it seems like D-Link does care more about us
than some other vendors: someone asked them for a redistribution license
of the binary firmware files, and they (D-Link Germany) rather quickly
followed up and granted redistribution (which quite surprised me, I have
to admit). Together with actually wanting to release a Linux driver for
TI cards (see above), this puts D-Link in a rather positive light...

Finally, let me mention that we really dislike the way how
Texas Instruments handles Linux driver support. It's a 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...)
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...

For an example of a vendor whose actions I deem useful, let me just mention
Sitecom. They list Linux compatibility status for many of their products on
their website, and from the look of it they clearly support Linux quite
actively. (UPDATE: they also screwed up in a big way. See above. :-\)

Have fun!

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