
STEP I: Kernel compilation
--------------------------------------------------------------------------------
NOTICE: Sometimes, you may not have to build your kernel manually. This happens
when you are so lucky that your precompiled kernel which your distribution uses
fullfills all the requirements mentioned below. However, in any case you still
have to obtain the kernel sources that correspond to your running kernel, and
put them in the right place.
To configure your kernel build options, in the kernel source directory
(most probably /usr/src/linux-2.x.x), do a `make menuconfig` under console
or `make xconfig' under X environment. (If no such dir exists, this means that
you have no kernel sources, and you have to install them)
The following parameters must be configured, in order for the driver to work:
- Loadable Module Support -> Enable (Module unloading is also recommended)
- Processor types and features -> Symmetric Multiprocessing Support - Disabled
- Device Drivers -> Networking Support -> Wireless LAN (non-hamradio)
        No further specific drivers need to be selected there.
- (PCMCIA only) Bus Options -> PCMCIA/CardBus support -> yenta-compatible.
        Select this only if you prefer to use internal card services
	Otherwise, When you build the external package pcmcia_cs,select i82365.
	You may have to edit /etc/sysconfig/pcmcia, filling the `PCIC=' field,
	with `i82365' or `yenta_socket', according to your selection.
- (USB only) The appropriate host controller interface has to be selected. 
	If unsure, select both ehci, ohci and alternate-uhci and you'll 
	later determine which one is actually used.
- (USB for 2.5 and 2.6) In order to make the driver work for 2.6 kernels,
	you have to download and install the reset-usb kernel patch.
	To make things easier, we provide a link to download the patch from 
	(atmelwlandriver.sourceforge.net/downloads.html).
	Gzip -d it, Copy the ungzipped file to /usr/src/linux-2.6.x and run:
	#patch -bf -p1 < patch_atmel_reset
	This keeps backups of the updated files, in case something goes wrong.
	After the patch has been applied, rebuild your kernel.

To find out if your kernel (custom or not) has these parameters configured as 
required, view the file /usr/src/<Your Running Kernel>/.config and check if the
following lines are the same. 
(they wont be found together, you have to search for each one of them)

CONFIG_MODULES=y
CONFIG_MODULE_UNLOAD=y 		# recommended
# CONFIG_SMP is not set
CONFIG_NET_RADIO=y		# to enable wireless extensions
CONFIG_NET_WIRELESS=y

CONFIG_PCMCIA=y			# mandatory for pcmcia
CONFIG_YENTA=y			# or `=m', if you intend to use external cs
CONFIG_CARDBUS=y

CONFIG_USB=y			# mandatory for usb
CONFIG_USB_EHCI_HCD=m		# `=m' to all 3 HCI's is the least risky option
CONFIG_USB_OHCI_HCD=m		# therefore `=y' is not recommended.
CONFIG_USB_UHCI_UHCI_ALT=m	# you only need to select the one that suits you
				# but selecting all of them won't do any harm
				

WARNING: There are serious conflicts when our driver tries to cooperate with 
usb-uhci, that can lead to a crash. Using uhci (instead of usb-uhci)
is higly recommended. So, if your system starts with usb-uhci loaded 
(you can see this with lsmod), rmmod it and load manually uhci.o (or uhci-hcd.ko
for 2.5+ kernels). In kernel Configuration, select as module only the alternate
UHCI driver if your bus is of that type.


Some further info for linux newbies:
After having finished with kernel tweaking, do `make bzImage', `make modules'
and `make modules_install'.
(For 2.4.x kernels, `make dep' must be run after exiting `make config')
The kernel image shall reside in ./arch/i386/boot/bzImage and should be copied
to /boot directory. For GRUB, just adding a section (in /boot/grub/menu.lst)
containing the new kernel image, is enough to activate the newly compiled kernel
and to be able to load it when booting.



STEP II: Building the Driver Modules
--------------------------------------------------------------------------------
Unpack the tarball (tar jxvf) and chdir to atmelwlandriver.
Be sure to run any of the following commands as superuser.
# make 
This will display all the available build options:

Pick one of the following targets for KERNELS 2.X.X:
make clean	- remove all directories of object files
make device buildonly=argument 
		- where device = usb or pcmcia, argument = debug or release
make lvnet	- compile lvnet utility
make winter 	- compile winter utility 
make world	- compile all modules with debug and release information
make install	- install modules and programs
							
example:
# make pcmcia buildonly=debug 
Builds every pcmcia module with debug information 

It is generally recommended when trying the drivers for the first time, 
to build them in debug mode, so as to determine easier whatever
can be responsible for a potential error. Be prepared, however, for a
great console output. (this can be ceased by `echo 0 >/proc/sys/kernel/printk')
The two applications accompanying the drivers are `lvnet' and `winter' and are
suited for console and X respectively. lvnet requires ncurses, while winter is a
wxWidgets app, therefore it needs wxGTX-4.2 or greater.Both must be run as root.

Having finished with building procedure, run:
# make install
This will copy the modules to a directory inside:
/lib/modules/<Your Running Kernel>/kernel/drivers/ , depending on the selected
bus, and shall report to modprobe about their existence, so that it
can find and load them, resolving their dependencies.


Possible Complications:
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
i) An error was encountered during `make all', hence building has been aborted.
This usually happens with newly introduced kernels. Apparently, something in the
linux kernel has changed or is no longer where it was expected to be. It could
be a header file or a variable name that has changed, or a function's parameters
that differ. A common cause of that error is the use of custom kernel sources
provided along with a distro, even for an older kernel version.
This is not surprising, since the linux kernel is a totally dynamic collection
of drivers. What you have to do, anyway, is:
Check out if you have the complete kernel sources of the same version with your
running kernel. If there are reports for a missing file, check if the file 
exists in another path than that where it is expected to be found, and try to
resolve the conflict manually. (a symbolic link would be fine)
Whether the problem was solved or not, please send us a report, describing the
error you encountered (see Appendix I: Reporting Errors)

ii) Make install fails.
The most common cause of this, is missing the directory where the modules should
be copied. Try to find if your modules were actually copied somewhere inside 
`/lib/modules/<Your Running Kernel>/' and if not, copy them manually to the
place where modules of this category reside. This should be `./pcmcia/', 
`./kernel/drivers/net' or './kernel/drivers/usb/' or so. Then depmod -a to 
inform modutils about the change.

iii) `depmod -a` fails.
If you receive the message `depmod cannot be found' the execute `su -' and 
`make install' again. If you notice some errors when running depmod, make sure
they have to do with the driver. In the case that they really have, then this
means that the module wouldn't be able to load anyway. Check the requirements
mentioned in Step I, try to determine which modules contain the missing
variables that depmod complains about, and rebuild your kernel to enable those
modules. Before rebuilding, it would be a good idea to insmod the driver just
to see if you can get more evidence about what's going wrong.
(or even insmod -f for risky ones, which forces the module to load, but
increases the chances for a complete crash)



STEP III: Setting up Configuration Scripts
--------------------------------------------------------------------------------
./scripts/atmel.conf
This file contains all the information that lets your system know which driver
it should load for any pcmcia atmel wlan device.
Therefore, editing it can serve a very specific purpose:
If no driver is loaded for your pcmcia wlan device, but you know for sure that
it contains an atmel chipset (you can visit linux-wlan.org to verify it) then
you have to add it on your own. First do a `cardctl ident' with your card
inserted. This will give an output of such form:
....
Socket 1:
	product info: "CARD's VENDOR", "YOUR DEVICE ID"
	manfid: 0x0000, 0x0000
	function: 6 (network)
From the above, we keep the `product info' field. That's all we need.
To make your card recognizable, you have to add a registration to atmel conf:
card "YOUR DEVICE NAME"
	version "CARD'S VENDOR", "YOUR DEVICE ID"
	bind "pcmfxxxx"
In the third line, `bind' command defines the module that should be loaded upon
card insertion. To activate changes you have to run `make install' again.
You can send us a report with the lines of your card's registration, to be
included in atmel.conf for everybody.

/etc/pcmcia/wireless.opts , /root/.vnetrc and /sbin/iwconfig
The files wireless.opts (for PCMCIA) and .vnetrc (for USB) are the startup
scripts for your card, if wireless extensions are enabled.
Don't worry, you 'll know if they aren't enabled. Nothing else regarding the
wlan would work without the extensions. You can run `#/sbin/iwconfig' to make
sure about it. If wireless extensions are disabled, this means that you have to
read `Step I' even more thoroughly, especially the part about enabling Wireless
LAN (non-hamradio).  As you'll see from the given examples within the script,
whatever parameter you need to be set upon card insertion, you can add it there.
To see the state of your card when you plug it, you can always run iwconfig
(prior or post to setting up wireless.opts). iwconfig can also be used to set
values at will, and that's what these scripts actually do.



STEP IV: Loading the Driver
--------------------------------------------------------------------------------
If the drivers are compiled and installed properly, then upon card insertion the
driver will be automatically loaded, as well as any module that it requires.
For pcmcia devices, when inserting the card right after `make install'
(without restarting any service) it may seem that nothing happens. You have to 
run: `/etc/init.d/pcmcia restart' for changes to take effect, or load the driver
manually with `modprobe pcmfxxxx`.
For usb, make sure, before plugging in the card, that the appropriate host 
controller module has been loaded. Use lsmod to verify it.

Possible Complications:
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
i) When I insert my pcmcia mac, my system crashes.
Try to reconfigure cardbus support, editing /etc/sysconfig/pcmcia.
(/etc/defaults/pcmcia for debian). Play with n value of the field
PCIC_OPTS="irq_mode=n". Alternate yenta_socket and i82365.
If still in trouble, send a report to the mailing list.

ii) Nothing happens upon card insertion.
If your card is of pcmcia type, the commands `cardctl status' and
'cardctl ident' may help you figure out what's going on. Ejecting and 
reinserting the card may help under problematic controllers or slots.
Restart pcmcia services, watch the file /var/log/messages, lsmod to see if the
driver has been loaded and, if not, load it manually.



STEP V: Enabling Ethernet Interface
--------------------------------------------------------------------------------
The ethernet name of the device is atmlN, where N is 0,1... depending on how 
many atmelwlan devices you have installed. Those being experienced with the
drivers in the past, will remember it taking common ethN names. However,
changing name was important for the interface to be easier distinguished.
Since there is no premade network script for atmlN devices, a good practice 
would be to find ifcfg-eth0 and make a duplicate of it onto ifcfg-atml0 and so
on. You shall need to modify it, according to your local network configuration.
The directory containing such network scripts varies.
(it  is /etc/sysconfig/network-scripts/ (redhat) or /etc/sysconfig/network/
(suse), or /etc/find_it_yourself)
An example of how ifcfg-atml0 should look like, is this:
DEVICE=atml0	# working with "alias atml0 <your device driver>" in 
		# /etc/modules.conf for automatic loading
BOOTPROTO=dchp	# or `static', if you wish, followed by an IPADDR=... setting
ONBOOT=no	# had better get enabled when plugging in the card

Running then `ifup atml0' will suffice to get an ip address, if your network 
services have been set up properly.



STEP VI: Applications
--------------------------------------------------------------------------------
i) lvnet
Lvnet is a console, ncurses-faced utility to configure your wireless nic.
To avoid problems, you have to run it as root, under a real tty. (not an X one).
It provides five tabs: View Config, Advanced, Security, Configure Card and 
Site Survey. You can navigate through them using left and right arrow keys.
"View config" will display an output similar to running `#/sbin/iwconfig',
containing values that indicate the state of your device.
"Advanced" tab contains more specific-purpose parameters for advanced users.
"Security" lets you set WEP keys, level, transmission key and authentication 
type, in order to associate to an AP that requires encryption.
In "Configure Card" you can set almost every writable setting of the card.
Finally, in "Site Survey", you can scan for access points and connect to any one
of them, if you can authenticate your connection.
F1 key exits a tab or terminates the program, if not inside a tab.

ii) winter
Winter is an X application, made with wxWidgets (former wxWindows) that provides
a visual environment to configure and manage your card. To be able to build it,
you need to have wxGTK-4.2 or greater. It's functionality is similar to that of
lvnet, extended by very useful features such as profiles, localization and
support for more than one devices alternatively.

iii) atmelup and fucd
These are both firmware upgrade tools, for console and X correspondingly.
The requirements of fucd are the same as those of winter, since they are both
powered by wxWidgets. Atmelup takes a single argument to run, which of course is
the .rom file containing the new firmware for upgrade. Do not ever use any other
file type. (fwr*.h are NOT conventional .rom files, so please do NOT use them)
Although a firmware upgrade is a simple matter of 3 minutes, great care must be
taken, for a single mistake can make your device totally, completely and
unrecoverably useless. Avoid running any wlan monitor app, since during the
upgrade, the card's drivers are unloaded. A known issue: In fucd, you cannot
separate two devices of identical type, when trying to select which one to
upgrade. The safest way in this case, is to unplug the one that does not need
upgrading, and rescan the usb busses, rather than trying to guess which one
comes first.


Possible Complications:
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
i) My system starts on X, but I insist on running lvnet. When trying to run it 
on a virtual terminal, it exits without any sign or warning. What shall I do?

<Ctrl>+<Alt>+<F1-6> switches to a system console. <Alt>+<F7> gets you back to X.
In a real console, you can run lvnet without problems concerning its appearance.
You can also try to maximize a virtual terminal, and see if lvnet runs.

ii) I can't start winter because of a stale lock.
This file prevents more than one instances of winter running at the same time. 
It is created when winter starts, and it is deleted when winter exits. However,
if the program crashes, (which will most probably happen if you detach your 
device while working with winter), the stale lock is not deleted. You can always
delete it manually.



Appendix I: Reporting Errors
--------------------------------------------------------------------------------
There are two mailing lists, hosted by sourceforge, that support atmelwlandriver
One for user questions, error reports, etc:
	atmelwlandriver-users@lists.sourceforge.net
and one related to developer issues: 
	atmelwlandriver-develop@lists.sourceforge.net

Things you need to specify when reporting an error to the users mailing list:
- Your linux kernel version
- The name of your distribution
- Your chipset id and the driver module that it uses, or should be able use.
- Your driver build configuration. Only the options you enabled are needed,
  ie. pcmcia - 502rfmd, debug.
- Your gcc version (if the error occured during driver compilation)
- The output of lsmod and lspci.
- Your usb or pcmcia controller and the name of the driver it uses.
- The error log, at the time that it happened. You may have to build the debug
  version of the drivers, in order to obtain a complete and descriptive error
  log, that 'll help us determine the nature of the problem. Also try to include
  the actions that were performed before the error occurred. OTAH, try to be
  specific: endless logs that contain useless information cause mailing
  pollution, thus they are not recommended.
- If there is a specific application facing problems, you could mention its
  whereabouts (ie. is it an Xapp or a console one? does it need some specific
  firmware or driver features?)


author: Titos Mpetsos (tmpetsos@patras.atmel.com)
Feel free to send any corrections, suggestions, reports...regarding this readme.
Many thanks to all you guys supporting the atmelwlandriver mailing lists.

