VERY OBSOLETE linux-wlan-ng master repository
Go to file
mark 24570e693b At Pavel's prompting, I'm codifying the release policy. 2001-12-14 19:48:31 +00:00
add-ons Added keygen after someone pointed out that it wasn't included in the 2001-12-13 20:45:49 +00:00
doc At Pavel's prompting, I'm codifying the release policy. 2001-12-14 19:48:31 +00:00
etc theBS's patch for installing the INSTFIXED scripts for USB and for 2001-12-13 19:34:48 +00:00
man Changed the comment header at the top of all the files to reflect the new company name. 2000-07-05 04:57:04 +00:00
scripts PDA display program from proskin. 2001-03-11 03:18:54 +00:00
src New files added for wireless extensions. 2001-12-13 22:15:02 +00:00
AVS.rmdirs Initial checkin. 2001-03-24 21:39:56 +00:00
CHANGES Updated for makefile fix. 2001-12-13 22:06:27 +00:00
COPYING Changed the comment header at the top of all the files to reflect the new company name. 2000-07-05 04:57:04 +00:00
Configure Added the hack to set CONFIG_NETLINK on the command line if the autoconf.h 2001-12-12 18:58:28 +00:00
LICENSE Initial add of the MPL version 1.1. 2000-02-07 19:26:25 +00:00
Makefile Rather huge patch submission from Bob James of Rebel. See CHANGES for 2001-04-05 20:38:49 +00:00
README Reworded the USB reset stuff. 2001-12-12 00:37:33 +00:00
THANKS rfloeter's Wireless Extensions patch. 2001-12-13 21:19:33 +00:00
TODO TODO comment about moving Wireless Extensions code up to p80211. 2001-12-13 21:35:55 +00:00
config.in Updated to version 0.1.13-pre1 2001-12-13 15:27:36 +00:00

README

* README
*
* Copyright (C) 2001 AbsoluteValue Systems, Inc.  All Rights Reserved.
* --------------------------------------------------------------------
*
* linux-wlan
*
*   The contents of this file are subject to the Mozilla Public
*   License Version 1.1 (the "License"); you may not use this file
*   except in compliance with the License. You may obtain a copy of
*   the License at http://www.mozilla.org/MPL/
*
*   Software distributed under the License is distributed on an "AS
*   IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
*   implied. See the License for the specific language governing
*   rights and limitations under the License.
*
*   Alternatively, the contents of this file may be used under the
*   terms of the GNU Public License version 2 (the "GPL"), in which
*   case the provisions of the GPL are applicable instead of the
*   above.  If you wish to allow the use of your version of this file
*   only under the terms of the GPL and not to allow others to use
*   your version of this file under the MPL, indicate your decision
*   by deleting the provisions above and replace them with the notice
*   and other provisions required by the GPL.  If you do not delete
*   the provisions above, a recipient may use your version of this
*   file under either the MPL or the GPL.
*
* --------------------------------------------------------------------
*
* Inquiries regarding the linux-wlan Open Source project can be
* made directly to:
*
* AbsoluteValue Systems Inc.
* info@linux-wlan.com
* http://www.linux-wlan.com
*
* --------------------------------------------------------------------
*
* Portions of the development of this software were funded by 
* Intersil Corporation as part of PRISM(R) chipset product development.
*
* --------------------------------------------------------------------

=======================================================================
Description:
The linux-wlan package is a linux device driver and subsystem
package that is intended to provide the full range of IEEE 802.11 MAC
management capabilities for use in user-mode utilities and scripts.
The package currently supports the Intersil 802.11b Prism2, Prism2.5, 
and Prism3 reference designs for PCMCIA, PCI, and USB.  Additionally,
the package includes support for PLX9052 based PCI to PCMCIA adapter
with a few different PCMCIA cards.

For a list of elements that are still undone, see the TODO file in 
this directory

=======================================================================
License:
See the COPYING and LICENSE files.

=======================================================================
Top level directory for linux-wlan-ng:
./add-ons	- additional programs that are not build from the 
                  top level make file
./doc		- source distribution documentation
./etc		- scripts used at run-time
./man		- man pages
./scripts	- contributed scripts that may do useful things
./src		- source code for various components


=======================================================================
Test Configurations:
This release was tested on the following configurations:

Intel:
   Kernel | pcmcia_cs | Distribution |  Device Types    
   -------+-----------+--------------+---------------------------------------
   2.2.20 | 3.1.29    | Debian woody |  Prism2-PCMCIA-PFlash
          |           |              |  Prism2.5-PCMCIA-PFlash
          |           |              |  Prism2.5-PCI-PFlash
          |           |              |  Prism2.5-USB-PFlash
          |           |              |  Prism3-PCMCIA-PFlash
   -------+-----------+--------------+---------------------------------------
   2.4.14 | 3.1.28    | Debian woody |  Prism2-PCMCIA-PFlash
          |           |              |  Prism2.5-PCMCIA-PFlash
          |           |              |  Prism2.5-PCI-PFlash
          |           |              |  Prism2.5-USB-PFlash
          |           |              |  Prism3-PCMCIA-PFlash

PowerPC:
   Kernel | pcmcia_cs | Distribution |  Device Types    
   -------+-----------+--------------+---------------------------------------
   2.2.13 | 3.1.10    | Custom       |  Prism2-PCMCIA-PFlash
          |           |              |  Prism3-PCMCIA-PFlash


=======================================================================
Build Instructions:

NOTE: You may not need to build at all.  Check the linux-wlan ftp site
      for binary packages built by AVS.  At the time of this writing the
      following targets were supported:
        RedHat 7.1
        RedHat 7.2
        Mandrake 8.1

NOTE: This release supports building four different drivers:

   prism2_cs	Driver for Prism2.x & Prism3  PCMCIA cards.
   prism2_pci	Driver for Prism2.5 (ISL3874) based _native_ PCI cards.
   prism2_plx	Driver for Prism2.x PCMCIA cards when used with 
		a PLX9052 PCI/PCMCIA adapter.
   prism2_usb   Driver for Prism2.x USB adapters.


Prerequisites:

To build linux-wlan-ng you will need:
   - Configured kernel source code for the kernel you are running.  
     Ideally, this will be the resulting tree after building your own 
     kernel.  Configured means that you have at least run 'make config',
     'make menuconfig', or 'make xconfig'.  If you are trying to build
     linux-wlan-ng for a previously existing kernel binary (one you did 
     not build yourself), look for help on the mailing lists because it 
     can be tricky.  I always run against kernels I've built myself, so I'm 
     not much help in this area.
   - If you are building a driver for a PCMCIA card, you will also need
     the configured PCMCIA source code for the pcmcia_cs subsystem you
     are currently running.

Building linux-wlan-ng:

1)  untar the package using the command:

    tar zxvf linux-wlan-ng-X.Y.Z.tar.gz

2)  Make sure you have configured kernel and (optionally) pcmcia sources on 
    your system.  Note that if you are _only_ building the prism2_pci,
    prism2_plx, or prism2_usb drivers you don't need the pcmcia-cs 
    source tree.

3)  To clean up any unwanted files accidentally included in the tar package,
    run 'make clean'.  If make clean behaves badly (infinite loop, for
    example), you may have a date/time mismatch.  Run the command:

    find . -type f -exec touch {} \;

    to fix the date&time stamps, then run 'make clean' again.


4)  To configure the linux-wlan-ng package, run 'make config'.  The 
    following set of questions will be asked. The default answer is in
    braces (e.g. []).  Just press <Enter> to select the default answer:

   - "Build Prism2.x PCMCIA Card Services (_cs) driver? (y/n) [y]: "
        Select "y" if you want to build the Prism PCMCIA driver.
        If you select "n", the PCMCIA related questions below
        will not be asked.

   - Build Prism2 PLX9052 based PCI (_plx) adapter driver? (y/n) [y]: 
        Select "y" if you want to build the Prism driver for 
        PLX PCI9052 PCI/PCMCIA adapter based solutions.

   - Build Prism2.5 native PCI (_pci) driver? (y/n) [y]: 
        Select "y" if you want to build the Prism driver for 
        Prism2.5 ISL3874 based native PCI cards.  This includes
        PCI add-in cards and the mini-pci modules included in some
        notebook computers (but not all, some use internal USB modules).

   - Build Prism2.5 USB (_usb) driver? (y/n) [y]: 
        Select "y" if you want to build the Prism driver for 
        Prism2.5 ISL3873 based USB adapters.  This includes
        USB add-on modules and the internal modules included in some
        notebook computers.

   - Linux source directory [/usr/src/linux]: 
        The config script will attempt to automagically find your kernel
        source directory.  If found, the kernel source source directory
        will be presented as the default selection.  If the default
        selection is wrong, you may correct it here.

   - pcmcia-cs source dir [/usr/src/pcmcia-cs-3.1.29]: 
        If the "_cs" driver is selected above, the configure script will
        attempt to present a reasonable default for the pcmcia source
        directory.  If the presented directory is incorrect, you may
        change it here.  If the "_cs" driver is not selected, this
        prompt will not appear.

   - Build for Kernel PCMCIA? (y/n) [n]: 
        If the "_cs" driver is selected, we need to know if you are
        intending to use the kernel pcmcia code rather than pcmcia_cs.
        This prompt will not appear if the "_cs" driver is not selected.
        NOTE: AVS in-house testing is done almost exclusively using the
              pcmcia_cs package with kernel pcmcia disabled.  Therefore,
              your results with kernel pcmcia may vary.

   - PCMCIA script directory [/etc/pcmcia]: 
        If the "_cs" driver is selected, this prompt allows you to 
        change the location where the pcmcia scripts will be installed.
        Only do this if you have installed the rest of the pcmcia_cs
        scripts to a non-default location.

   - Alternate target install root directory on host []:   
        This prompt allows you to specify an alternative root directory
        for the install process.

   - Module install directory [/lib/modules/2.2.20]: 
        Select where you want the driver modules to be installed.  The
        script constructs a default location using the output of uname.
        If you have not yet installed the kernel you will run linux-wlan
        with, and the new kernel has a different version string, you will
        need to change this value.

   - Target Architecture? (i386, ppc, or alpha) [i386]: 
        On some targets, we can't identify the target processor from
        compiler settings or predefined symbols.  Therefore, we need an 
        explicit setting that identifies the target CPU.

   - Prefix for build host compiler? (rarely needed) []: 
        When cross-compiling or using different compilers for kernel and
        user-mode software, it is sometimes (but rarely) necessary to 
        specify a different compiler prefix to use when compiling the 
        _tools_ that are built to run on the build host during the 
        linux-wlan-ng build process.

   - Compiling with a cross compiler? (y/n) [n]: 
        If you are cross compiling, we need to enable the building of
        the linux-wlan-ng build-time tools using the local host compiler
        rather than the cross-compiler.

   - Build for debugging (see doc/config.debug) (y/n) [y]: 
        This option enables the inclusion of debug output generating
        statements in the driver code.  Note that enabling those statements
        requires the inclusion of insmod/modprobe command line arguments
        when loading the modules.  See the document doc/config.debug
        for more information.


5)  To build the package, run 'make all'

6)  To install the package, run 'make install' (as root).

=======================================================================
Configuring:

------------------------------
FOR PCMCIA USERS:
A)  Edit the /etc/pcmcia/wlan-ng.opts file to configure. These options are
    set every time you insert a card.  If you want to change an option
    after the initial configuration, a) pop your card out, b) alter the 
    file, c) insert your card.  For more information see the file(s)
    linux-wlan-ng*/doc/config.*

B)  Edit your network.opts file to set up your IP settings.  Note: for a 
    station, the SSID you're connecting to will be appended to the 
    current pcmcia scheme name.  You can use this to have different
    IP setups for different wireless LANs you connect to (e.g. home vs. work).

C)  Restart pcmcia-cs with the command:

    /etc/rc.d/init.d/pcmcia restart

D) Insert the card.  For most cards, a solid LED indicates that the 
    SSID you specified was found, a bss was joined, and the firmware 
    completed the authenticate and associate processes.

E) Run ifconfig and route to determine if your IP and route settings are
    listed as you wanted them.  It's also a good idea to look at the file
    /etc/resolv.conf to see if your nameserver address has been set up 
    correctly.

------------------------------
FOR PCI OR PLX USERS:
A) You must make sure that the drivers get loaded at boot time and that the 
   necessary initialization takes place.  The simplest way to do this is
   to add the following commands to your rc.local file:

     modprobe prism2_pci
     wlanctl-ng wlan0 lnxreq_autojoin ssid=<your APs SSID> authtype=opensystem
     ifconfig wlan0 <yourIP> netmask <yourNetmask> broadcast <yourBroadcast>
     route add default gw <yourGateway>

   Also, don't forget to set up your resolv.conf to point at your DNS server.

B) If you are daring, you can try out the rc.wlan and wlan.conf scripts. 
   They do work, and they are installed into your */init.d directory and 
   /etc directory.  We don't currently
   create the soft-link from the runlevel directory to the wlan startup 
   script because the distributions vary too much in this respect.  You'll 
   need to create the soft-link yourself.  Just make sure it is early in the
   process, namely, before the the network interfaces are brought up.
   The actual setup of the SSID and such is in the file /etc/wlan.conf.
   Note that you'll also need to add an modules.conf alias statement 
   for the driver that you wish to load (pci or plx), we don't explicitly
   load a module in init.d/wlan because we don't know which one you want. ;-)

------------------------------
FOR USB USERS:

A) Make sure your kernel usb support is running
B) Plug in the Prism2.x USB device
C) Run 'modprobe prism2_usb prism2_doreset=1' to load the driver into memory.
D) Run 'ifconfig wlan0 up' to initialize the MAC
E) Run 'wlanctl-ng wlan0 lnxreq_autojoin ssid=<your ssid> authtype=opensystem'
   to enable the MAC in Infrastructure Station mode.
F) Run 'ifconfig wlan0 <your IP address>'

NOTE: USB devices can use the /etc/init.d/wlan script for initialization.
      Integration with usbmgr/hotplug is still a TODO item.

IMPORTANT: Due to an issue with the current firmware in Prism USB devices,
the driver must do a port reset (which is normally handled by usbcore).  

Some usb low-level drivers don't like this, they see it as a new device 
connect (of something that's _already_ in the connected state).  When that 
happens things go very awry, possibly crashing and/or hanging the machine.  

Some low-level drivers handle it just fine.  

Since it appears to be a combination of the underlying USB host hardware 
_and_ the usb low-level driver _and_ the linux usb version, I haven't been able 
to put together a description of precisely which hardware/software will work.
Some of my hardware here in the lab works, some hardware (with exactly the 
same software) does not.

You will have to experiment on your own.

Unfortunately, there's nothing we can do about it until new firmware
becomes available.  The good news is that the firmware developers are aware
of the problem, they have a fix, and the new firmware is coming, we just
don't know precisely when it will be available.  It all depends on how quickly
they can get it through their QA process.  When it does become available,
install it in your device using the Windows firmware update utility, 
remove the "prism2_doreset" on the modprobe command line above and everything
will work just peachy.