Merge remote-tracking branch 'regmap/topic/core' into regmap-next

[deliverable/linux.git] / drivers / staging / wlags49_h2 / README.wlags49

==============================================================================
Agere Systems Inc.                                                   July 2004
Readme for Linux Driver Source for Wavelan                   Version: 7.22-abg
==============================================================================

This text file includes update information, installation instructions,
limitations to the current version of the product, and suggestions to solve
known issues or problems.


TABLE OF CONTENTS.

1.  DESCRIPTION
2.  SYSTEM REQUIREMENTS
3.  NEW IN THIS RELEASE
4.  INSTALLATION NOTES
5.  TECHNICAL CONSTRAINTS
6.  KNOWN ISSUES
7.  TECHNICAL SUPPORT

------------------------------------------------------------------------------
1.  DESCRIPTION

    With this package, you can build and install a Wireless driver for a
    specific Linux kernel.

    The driver in this package supports the network interface cards based on:
     - WL60010, a.k.a. Hermes-II
     - WL60040, a.k.a. Hermes-II.5

    Although derived from the Hermes-I/II Linux driver, this release ONLY
    Supports Hermes-II/II.5 chipsets.  Hermes-I is no longer supported.

    The software is distributed in a compressed source file archive:
     - wl_lkm_7_22_abg.tar.gz

    Because this release supports more than one Hermes CPU and bus
    architecture, a naming convention is used for the resulting binaries that
    can be built from this source code. Driver binaries are named as follows:

    wlags49_<hermes_type>_<bus_arch>.o

    where 'wlags49' denotes an Agere WaveLan Linux build,

    <hermes_type> is: 'h2' for Hermes-II, 'h25' for Hermes-II.5

    <bus_arch> is: 'cs' for Card Services (PCMCIA, Compact Flash), PCI for
    PCI or MiniPCI.

    For example, a driver built for Hermes-II Card Services (PCMCIA/Compact
    Flash) is named wlags49_h2_cs.o, whereas a driver built for Hermes-II
    MiniPCI is named wlags49_h2_pci.o.
    The following software is included with this distribution:

    General information:
    * README.wlags49              This file
    * LICENSE.wlags49             License
    * wlags49.mk                  Top level Makefile
    * Build                       Script to build driver
    * Install                     Script to install driver

    Driver source:
    * wireless/                   MSF source
    * hcf/                        HCF and F/W source
    * wireless/wlags49_cs.mk      Driver Makefile, PC Card
    * wireless/wlags49_pci.mk     Driver Makefile, PCI
    * include/hcf/debug.h         Driver debug support
    * include/hcf/hcfcfg.h        Header to configure HCF
    * include/wireless/*.h        Driver source headers

    Driver online manual page:
    * man/wlags49.4               Driver manual page

    PCMCIA configuration update:
    * etc/wlags49.conf            Add-on config file
    * etc/wlags49.mk              config update Makefile
    * etc/wlags49.patch           config update patch file

    The driver is build up of 2 modules:
     - a higher module called Module Specific Functions (MSF), which contains
       the functions of the driver that are network driver interface and
       Operating System specific.
     - a lower module called Hardware Control Functions (HCF), which contains
       the functions to interface to the Network Interface Card (NIC).  The HCF
       provides for all WaveLAN NIC types one standard interface to the MSF.
       This I/F is called the Wireless Connection Interface (WCI) and is the
       subject of a separate document (025726).

    The HCF directory contains firmware images to allow the card to operate in
    either station (STA) or Access Point (AP) mode. In the build process, the
    files fw_h2.c and fw_h25.c are used for Hermes-II and Hermes-II.5
    respectively. The firmware images in this release are identified as:
         - HII Station F/W:      fw_h2.c.sta
         - HII.5 Station F/W:    fw_h25.c.sta
         - HII AccesPoint F/W:   fw_h2.c.ap
         - HII.5 AccesPoint F/W: fw_h25.c.ap
        To build a STA or AP mode driver, the suffix .sta or .ap must be removed.
        The files as distributed by this release build STA drivers by default.

------------------------------------------------------------------------------
2.  SYSTEM REQUIREMENTS

2.1 Operating System

    This software can be compiled and installed with Linux kernel versions
    2.4.x. Although this driver should compile for other CPUs as well, as of
    the date of this release, no CPU architectures other than x86 have been
    verified.

    wl_lkm_7_22_abg is tested with the following Linux Distributions:
    * Red Hat version 9.0
    * Suse    version 9.0

    If you're building for PC Card or Compact Flash, you need the Card Services
    from David Hinds.

    wl_lkm_7_22_abg is tested with:
    * pcmcia-cs-3.2.7.tar.gz

2.2 Free Disk Space

    To compile the software you need to have the full set of Linux kernel
    source files installed, as well as a sane build environment which includes
    all tools necessary for compiling and linking code. Depending on the exact
    version of the kernel, you need approximately 150 MB of free disk space.
    Once compiled, the driver uses about 150-200 KB.  Please note, this size is
    approximate and can vary depending on which version of the driver is built.
    In addition, adding debug tracing support increases this size.

------------------------------------------------------------------------------
3.  NEW IN THIS RELEASE

Version 7.22 abg - July 28, 2004

------------------------------------------------------------------------------
4.  INSTALLATION NOTES

    The driver files for the Linux driver are not "ready" for direct
    installation onto any Linux computer.  To build and install the driver you
    need some expertise on the Linux operating system in general and the type
    and version installed of the kernel installed on your computer.  With this
    knowledge you can use the driver source files provided to build your own
    Linux driver for your specific computer and kernel.

4.1 Before you start

    1) Determine the type and version of the Linux kernel of your computer and
    check whether it meets the system requirements listed in section 2 of this
    README.

    2) If you're building for PC Card or Compact Flash, read the Linux
    PCMCIA-HOWTO by David Hinds. This document is probably provided on the
    CD-ROM of your Linux distribution. You can download the latest version
    from:

        http://pcmcia-cs.sourceforge.net

   Please read the section titled "Prerequisites and kernel setup" of the
   PCMCIA-HOWTO.

4.2 Build the driver for PC Card / Compact Flash

    1) Obtain a copy of the Linux PCMCIA package from a CD-ROM of your Linux
    distribution or download the latest version.
    For your convenience, the Agere Systems Wireless CD-ROM contains a copy of
    the PCMCIA package in sub-directory: Xtras/Linux/PCMCIA

    2) To unpack the Linux PCMCIA package, copy it to the current working
    directory and type:
       % tar xzvf pcmcia-cs-x.y.z.tar.gz
       % mv pcmcia-cs-x.y.z pcmcia-cs

    Note: If you use the archive supplied on the CDROM, use archive name
    "pc3_2_1.tgz" instead of "pcmcia-cs-3.2.7.tar.gz".

    Note: even though PCMCIA code exists in the kernel source tree, the PCMCIA
    Card Services package needs to be unpacked locally to build drivers based
    on it.

    3) Extract the wlags49 distribution archive on top of the Linux PCMCIA
    package.
       % cd pcmcia-cs
       % tar xzvf ../wl_lkm_7_22_abg.tar.gz

    4) To build and install the driver, follow the procedure below:
       % ./Configure

    Answer the presented questions. Usually the default answers are OK and
    pressing "Enter" is enough.
    On newer RedHat systems, however, you should specify "/usr/src/linux-2.4"
    as the Linux source directory instead of the default "/usr/src/linux".

    For more detailed information on configuration, building and installing,
    see the PCMCIA-HOWTO.

    To build the default drivers, which support Hermes-II in station mode, run
    the Build script:
       % ./Build

    This script determines whether your system uses in-kernel PCMCIA and either
    builds the full PCMCIA package or just the driver.

    Before installing the driver with the Install script, you must become
    'root':
       % su
       ..
       % ./Install

    This script determines whether your system uses in-kernel PCMCIA and either
    installs the full PCMCIA package or just the driver.

    5) If it becomes necessary to clean the build, issue the following
    commands:
       % make clean
       % make -C lib clean

4.3 Build the driver for PCI

    1) Extract the wlags49 to the current working directory.
       % tar xzvf wl_lkm_7_22.tar.gz

    Note: there is no need to unpack the driver source into a PCMCIA build
    directory.

    2) To build the PCI driver:
       % make -f wlags49.mk wlags49_h2_pci
       or
       % make -f wlags49.mk wlags49_h25_pci

    3) Install the driver.
       % insmod ./wireless/wlags49_h25.o

    4) If it becomes necessary to clean the build.
       % make -f wlags49.mk pci_clean

4.4 Configure your Wireless PC Card

    There are 3 ways to configure the driver
    - module parameters (/etc/pcmcia/config.opts)
    - wireless extension (/etc/pcmcia/wireless.opts)
    - Agere configuration file (/etc/agere/iwconfig-eth#)


4.4.1 Configure through /etc/pcmcia/config.opts

    To use this method, make sure that /etc/pcmcia/wireless.opts file is either
    absent or contains blank parameter values as shown below.

    *,*,*,00:60:1D:*|*,*,*,00:02:2D:*)
        INFO=""
        ESSID=""
        MODE=""
        KEY=""
    ;;

    1) To configure the Wireless PC Card, please refer to:
       * The online manual page (wlags49.4)
         % man wlags49
       * The network adapter sections of the PCMCIA documentation.
         % more PCMCIA-HOWTO

    2) Use an editor to configure the module parameters:
       # vi /etc/pcmcia/config.opts

       a) To connect your computer to a wireless infrastructure that includes
       access points such as the AP-1000 or AP-500, you need to identify the
       network name of the wireless infrastructure.

       For example if your infrastructure uses the network name "My Network",
       edit the config.opts file to include the following:

       module "<driver_name>" opts "network_name=My\ Network"

       Notice that the space character needs to be escaped with a backslash.

       b) To connect your computer to a Residential Gateway RG-1000, you need
       to know the RG ID (=network_name) and the encryption key.  You can find
       the RG ID on a small label on the rear of the unit.

       For example if your RG-1000 has ID 225ccf and you did not change the
       encryption key yet, edit the config.opts file to include the following:

       module "<driver_name>" opts "network_name=\"225ccf\" key_1=\"25ccf\"
       enable_encryption=Y"

       If you changed your encryption key, you should specify this key as key_1
       on the parameter line.

       c) To connect your computer to a peer-to-peer network, in an environment
       without access points, the IBSS mode is recommended.

       For example to connect to a peer-to-peer network called "My Network",
       enter the following in the config.opts file:

       module "<driver_name>" opts "create_ibss=Y network_name=My\ Network"

       d) Optionally you can also include a "Station Name" value that can be
       used to indentify your computer on the wireless network.

       For example if you wish to name your computer "Wave1" when connecting it
       to a wireless infrastructure,  edit the config.opts file to include the
       following:

       module "<driver_name>" opts "network_name=Ocean station_name=Wave1"

       e) To connect your computer to an Ad-Hoc workgroup of wireless
       computers, enter the following in the config.opts file:

       module "<driver_name>" opts "port_type=3"

       Note that the "Ad-Hoc Demo Mode" is not the recommended mode for a
       peer-to-peer network.  The configuration of this  non-interoperable mode
       is only explained here for special applications (e.g. research, or
       compatibility with other / previous WaveLAN/IEEE products).

       The IBSS mode described in c) is the preferred and interoperable mode
       for creating a peer-to-peer network.

    3) Use an editor to modify the network options for your adapter.
       # vi /etc/pcmcia/network.opts

       The parameters need to be correct for the connected network. Check with
       your system administrator for the correct network information.  Refer to
       the PCMCIA-HOWTO for more configuration information.

       For example:
            *,*,*,*)
                IF_PORT=""
                BOOTP="n"
                IPADDR="10.0.0.5"
                NETMASK="255.255.255.0"
                NETWORK="10.0.0.0"
                BROADCAST="10.0.0.255"
                GATEWAY="10.0.0.1"
                DOMAIN="domain.org"
                DNS_1="dns1.domain.org"
                ;;

       RedHat and Suse do not use the network.opts to configure the driver.
       Instead RedHat uses a GUI-based tool called 'neat' ('net.cfg' in older
       versions) and SuSE Linux uses 'YaST'. These tools creates scripts, like
       ifcfg-eth0, in the directory /etc/sysconfig/network-scripts. Using the
       default GNOME menu, you can start netcfg from: Programs->System->Network
       Configuration.

    4) Restart the PCMCIA services.
       # /etc/rc.d/rc.pcmcia restart
         or
       # /etc/rc.d/init.d/pcmcia restart


    For a more detailed description about the various configuration options and
    definitions, please consult the Wireless documentation.

4.4.2 Configure through /etc/pcmcia/wireless.opts

    This driver has support for the "Wireless Extensions".  This interface
    allows the "Wireless Tools" to get statistics from the driver and allows to
    change the configuration of the driver on the fly.

    The latest versions of the PCMCIA package contain scripts that use the
    wireless extension to configure the driver as an alternative to the
    configuration through module parameters as described in section 4.4.1.
    Read the /etc/pcmcia/wireless.opts file for the theory of operation.  When
    the driver is configured, go to section 4.4.1 step 3 to configure the
    network parameters.

    For more information, refer to the following WEB pages:
    http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Linux.Wireless.Extensions.html
    http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html

4.4.3 Configure through /etc/agere/iwconfig-eth#

    In addition to using either the module options or the wireless extensions
    methods to configure a wireless device, this version of the software also
    supports an Agere specific implementation. This was done because:
    * Module options configures multiple devices the same.
    * Wireless extensions parameters do not cover all of the available options
      in the driver.

    For each wireless ethernet device (identified by eth<n>, where n is a
    positive integer), a file /etc/agere/iwconfig-eth<n> can be created which
    contains configuration information for a wireless device. For example, the
    file /etc/agere/iwconfig-eth1 is the config file for eth1. This file should
    contain Key/Value pairs in the format:

    <Key>=<Value>

    where <Key> is the parameter to configure and <Value> is the value to
    assign it. For example, if the config file /etc/agere/iwconfig-eth1
    described above contains the following:

    DesiredSSID=some_network
    EnableEncryption=Y
    Key1=net01
    TxKey=1

    this configures eth1 to associate to the ESSID 'some_network' with
    encryption on, where the the first encryption key is 'net01' and the key to
    use for encryption is Key 1.

    Note that this only works on Agere hardware which uses this driver. For
    other wireless drivers, or non-wireless devices, this file can be present,
    but has no effect.

    Please refer to the man page for more information on this configuration
    file and the parameters that can be set.


4.5 Configuring your Wireless PCI card

    Note that the above method of configuring the card using
    /etc/pcmcia/config.opts is only valid for PCMCIA/CF cards. For [mini]PCI
    and CardBus cards, refer to your system's documentation on modules.conf to
    load the driver with the proper options for a given wireless ethernet
    interface. In addition, network configuration tools like 'netcfg', 'neat',
    or 'YaST' (see Section 4.4.1, Step 3) can be used to configure the miniPCI
    card. Lastly, the Agere configuration file described in Section 4.4.3 may
    also be used for [mini]PCI and CardBus devices.

4.6 Troubleshooting

    When the Wireless PC Card is inserted, the card manager emit beeps in
    different tones to indicate success or failure of particular configuration
    steps.
      a) Two high beeps
         - The card was identified and configured successfully.
      b) One high beep followed by a low beep
         - The card was identified, but could not be configured.
         - Examine the system log (dmesg) for PCMCIA error or warning messages.
      c) One low beep
         - The card could not be identified.
         - Execute "cardctl ident" to display the adapter PnP information.
           Verify the PnP information matches an entry in the PCMCIA
           configuration file (/etc/pcmcia/config).
         - Examine the system log (dmesg) for PCMCIA error or warning messages.

    The Wireless PC Card has two LEDs that indicate the state of the adapter
    and network.
      * Power LED (toward the middle of the adapter)
        - This LED indicates power has been applied, and the card is
          functional. In normal operation mode with Card Power Management
          disabled, it is steady-on. With Card Power Management enabled, it
          blinks rapidly (several times per second).
      * Transmit/Receive LED (closer to the edge of the adapter)
        - This LED flashes when it detects transmit or receive packets.

      * Both LEDs blink at the same time every 10 seconds.
        - The adapter was unable to make contact with the named wireless
          network. Verify the network_name, in the config.opts file matches the
          network name of the access point.
      * LEDs indicate normal operation with the Power LED
        steady-on or blinking rapidly and Transmit/Receive LED flashing, but no
        traffic.
        - If the network is operating in normal mode (ie.  port_type = 0 or not
          specified), and a network_name has been specified, verify the
          workstation network parameters (ifconfig, route, etc.) are correct
          for the wireless network.
        - If the network is operating in Ad-Hoc (peer-to-peer) mode (ie.
          port_type = 3), the adapter needs another workstation/adapter to
          communicate with.  Verify the network parameters on both of the
          workstations (ifconfig, route, etc.) are correct.

    Refer to the online manual page for additional configuration, feature and
    support information.
       % man wlags49
         or
       % man 4 wlags49
         or
       % nroff -man wlags49.4 | more

4.7 Identifying the software

    This section explains how to identify the version of this software once it
    is unpacked or installed.

    The Linux Driver Source/Library distribution consist of two main
    components, the driver source and the HCF module.

    * To quickly identify the version of the source, type:
      % grep DRV.*VERSION include/wireless/wl_version.h
      #define DRV_MAJOR_VERSION   7
      #define DRV_MINOR_VERSION   22

    * To identify the revision of the HCF library contained in the driver,
      type:
      % grep HCF.Revision hcf/hcf.c
      #define HCF_VERSION  TEXT( "HCF$Revision: 1.8 $" )

    To identify a compiled wlags49 driver, go to the directory where the driver
    is located. Card Services drivers (wlags49_h2_cs.o and wlags49_h25_cs.o)
    are located in:
    /lib/modules/<kernel-version>/pcmcia

    PCI drivers (wlags49_h2.o) are located in:
    /lib/modules/<kernel-version>/kernel/drivers/net

    * To retrieve the version of the source used to compile the driver, type:
      % strings <driver_name>.o | grep Agere
      <driver_name> v7.22-abg-Beta for PCMCIA
      <driver_name> v7.22-abg-Beta for PCI

    * Likewise, to retrieve the revision of the HCF used to compile the driver,
      type:
      % strings <driver_name>.o | grep Revision
      HCF$Revision: 5.15

    At startup the wlags49 driver reports its version in the system log file
    (/var/log/messages).

------------------------------------------------------------------------------
5.  TECHNICAL CONSTRAINTS

    At the time of release of this software, the following constraints are
    identified:

5.1 Using the ISA adapter

    Description: To allow operation in desktop computers Agere also provides an
    optional ISA bus to PC Card adapter (also referred to as "swapbox").

    This ISA Adapter can be configured for two different I/O Address values:
      * 3E2 (factory-set default)
      * 3E0

    Impact: By default the i82365 module of the Linux pcmcia package only
    probes at 3E0.

    Actions:
    1) Read the manual page on the probing of the i82365 module, by typing the
    command:
        man i82365

    2) Apply one of the two following options:
       a) Change the I/O address strapping of the ISA adapter by replacing the
          jumper on the ISA adapter.  The correct jumper setting is pictured in
          the electronic "Wireless ISA Adapter, Getting Started Guide" provided
          on the Wireless Software CD-ROM. This guide is provided in Adobe's
          Acrobat PDF format.

       b) Alternatively, you can load the i82365 module with the
          "extra_sockets" parameter set to 1.

          On a RedHat 5.x thru 7.x, system, put this in the file
          "/etc/sysconfig/pcmcia":
             PCMCIA=yes
             PCIC=i82365
             PCIC_OPTS="extra_sockets=1"
             CORE_OPTS=
             CARDMGR_OPTS=

          For other Linux distributions, you are advised to consult the
          "PCMCIA-HOWTO" notes for information about changing the I/O Address
          probing.

5.2 Using the PCI Adapter

    Description: To allow operation in desktop computers Agere also provides an
    optional PCI bus to PC Card adapter (also referred to as "swapbox").

    For correct interrupt assignment, the system should support PCIBIOS 2.2.
    It is recommended to use PCMCIA package version 3.2.7 or higher.

    The default configuration of the interrupt routing method of the PCI
    Adapter's TI CardBus Controller is incorrect.

    Actions:
    1) Read the manual page on the "Options specific for TI CardBus
    Controllers" of the i82365 module, by typing the command:
        man i82365

    2) Load the i82365 module with the "irq_mode" parameter set to 0.
       On a RedHat 5.x thru 7.x system, put this in the file
       "/etc/sysconfig/pcmcia":
           PCMCIA=yes
           PCIC=i82365
           PCIC_OPTS="irq_mode=0"
           CORE_OPTS=
           CARDMGR_OPTS=

   For the location of the PCMCIA scripts on other Linux distributions, you
   are advised to consult the "PCMCIA-HOWTO", "Notes about specific Linux
   distributions".

------------------------------------------------------------------------------
6.  KNOWN ISSUES

    This is the current list of known issues for this release, and will be
    addressed in the near future:

    1. This driver release contains a version of Hermes-II.5 firmware which
    REQUIRES calibrated cards. If there is no calibration data present in the
    PDA of the hardware, the firmware does not operate.

    2. WDS is not yet supported.

    3. DMA is not yet supported.

    4. WPA is not yet supported.

    5. 32-bits I/O is not yet supported.

    6. The current Build script also builds the PCI drivers.

    7. The current Install script also copies the PCI drivers to the lib
    directory.

        8. If F/W files are required from outside this release, the entry points
        inside these F/W files have to be renamed from "ap" and "station" to
        "fw_image" and they have to be renamed to fw_h2.c and fw_h25.c for
        Hermes-II and Hermes-II.5.

------------------------------------------------------------------------------
7.  TECHNICAL SUPPORT

7.1 Finding Information

    On the Agere Systems Web Site you can find the most recent device drivers,
    software updates and user documentation.

    World Wide Web:    http://www.agere.com

7.2 Contact Technical Support

    If you encounter problems when installing or using this product, or would
    like information about our other "Wireless" products, please contact your
    local Authorized "Wireless" Reseller or Agere Systems sales office.

    Addresses and telephone numbers of the Agere Systems sales offices are
    listed on our Agere Systems web site.

    When contacting Technical Support, please use the Problem Report Form and
    send it to us by Fax or E-Mail.  The Problem Report Form 'REPORT.TXT'
    (Plain text format) is included on the disk. Alternatively, you can
    download the Problem Report Form from the Agere Systems web site.

    Include Product Name, Serial Number and software version number with each
    request to help the Support Group helping you.

==============================================================================
                          END OF FILE