Original 0.2.0pre6_plus_fixes_7 tarball

[acx-mac80211.git] / README

*******************************************************************************
*             Open-Source wireless driver for TI ACX100 chipset               *
*******************************************************************************


Let us first mention that this driver is supposed to support EVERY SINGLE CARD
with ACX100 chip (except for USB implementations, which are extremely rare
-- initial successful firmware loading support is in the driver now,
but it's far from working completely - 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.

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.
For now, you should take these unsupported cards back to the shop
where you bought them, mentioning completely missing unacceptable
driver support from Texas Instruments.

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+)
are:
DWL-G120 (PRISM GT chipset)
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 supported yet!)
DWL-G650+ (TNETW1130)

When looking at the DWL-G650 mess, I could puke again...
Again, these cards listed above will NOT work with this driver, you will
hopefully be able to find a different Linux driver supporting your card's
chipset...
Of course, all old DWL-120/520/650 cards also don't work with this
driver, since they used Prism2 (except for some rare samples of the
DWL-650, where D-Link ALSO used ACX100, confusingly).
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; 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.11b 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.

Skillful testers and BSD driver writers welcome!!
(for FreeBSD development, please contact mochaspirit AT users DOT
sourceforge DOT net)
There is a free download of the 802.11b spec at
http://standards.ieee.org/getieee802/

--- REQUIREMENTS ---

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. And of course you
need proper kernel header files / kernel source installed for the exact
kernel you're running!

Also, you need to have the package containing iwconfig, iwpriv & Co.
installed on your system (Debian: package wireless-tools).

Next, a firmware is needed.
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)
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+_driver_302.zip
unzip dwl520+_driver_302.zip
cp Win2000/WLANGEN.BIN Win2000/RADIO0d.BIN Win2000/RADIO11.BIN firmware/
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 individual radio
files (small firmware plus RFMD radio file plus Maxim radio file)
as well as combined versions (one bigger firmware, which is the old concept).
Here you have a choice, you can either copy the individual files over
(which will need to be renamed to the firmware names given above)
or use the combined file on its own. If you copy the combined file it must be
renamed to "WLANGEN.BIN".

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

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 (make sure to have package
  "make" installed on your system!), 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 ...
Again, no system installation is provided, since the various Linux
distributions often differ in their exact network configuration methods.
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/

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

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

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.

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!

-- 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 --
In case of ACX100 CardBus, 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 instead of e.g. i82365)
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.
Please tell us if this managed to resolve some issue with a particular card!
Use tools like "cardctl info", "lspci -v", "dump_cis".

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

-- 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 peer card).
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.
Make sure that network association is working properly!
(all steps that get listed from STARTED, SCANNING, WAIT_AUTH,
AUTHENTICATED to ASSOCIATED finish successfully)


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

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

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

--- 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 fix any
problems 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!
************************* !!!!!!!!!!!!!!!!!!!!!  *************************

--- 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 5 or 6
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 my "Most Braindead Hardware
Vendor 2003" award, 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