============================================================================== 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__.o where 'wlags49' denotes an Agere WaveLan Linux build, is: 'h2' for Hermes-II, 'h25' for Hermes-II.5 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 "" 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 "" 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 "" 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 "" 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 "" 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, where n is a positive integer), a file /etc/agere/iwconfig-eth 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: = where is the parameter to configure and 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//pcmcia PCI drivers (wlags49_h2.o) are located in: /lib/modules//kernel/drivers/net * To retrieve the version of the source used to compile the driver, type: % strings .o | grep Agere v7.22-abg-Beta for PCMCIA v7.22-abg-Beta for PCI * Likewise, to retrieve the revision of the HCF used to compile the driver, type: % strings .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