1============================================================================== 2Agere Systems Inc. July 2004 3Readme for Linux Driver Source for Wavelan Version: 7.22-abg 4============================================================================== 5 6This text file includes update information, installation instructions, 7limitations to the current version of the product, and suggestions to solve 8known issues or problems. 9 10 11TABLE OF CONTENTS. 12 131. DESCRIPTION 142. SYSTEM REQUIREMENTS 153. NEW IN THIS RELEASE 164. INSTALLATION NOTES 175. TECHNICAL CONSTRAINTS 186. KNOWN ISSUES 197. TECHNICAL SUPPORT 20 21------------------------------------------------------------------------------ 221. DESCRIPTION 23 24 With this package, you can build and install a Wireless driver for a 25 specific Linux kernel. 26 27 The driver in this package supports the network interface cards based on: 28 - WL60010, a.k.a. Hermes-II 29 - WL60040, a.k.a. Hermes-II.5 30 31 Although derived from the Hermes-I/II Linux driver, this release ONLY 32 Supports Hermes-II/II.5 chipsets. Hermes-I is no longer supported. 33 34 The software is distributed in a compressed source file archive: 35 - wl_lkm_7_22_abg.tar.gz 36 37 Because this release supports more than one Hermes CPU and bus 38 architecture, a naming convention is used for the resulting binaries that 39 can be built from this source code. Driver binaries are named as follows: 40 41 wlags49_<hermes_type>_<bus_arch>.o 42 43 where 'wlags49' denotes an Agere WaveLan Linux build, 44 45 <hermes_type> is: 'h2' for Hermes-II, 'h25' for Hermes-II.5 46 47 <bus_arch> is: 'cs' for Card Services (PCMCIA, Compact Flash), PCI for 48 PCI or MiniPCI. 49 50 For example, a driver built for Hermes-II Card Services (PCMCIA/Compact 51 Flash) is named wlags49_h2_cs.o, whereas a driver built for Hermes-II 52 MiniPCI is named wlags49_h2_pci.o. 53 The following software is included with this distribution: 54 55 General information: 56 * README.wlags49 This file 57 * LICENSE.wlags49 License 58 * wlags49.mk Top level Makefile 59 * Build Script to build driver 60 * Install Script to install driver 61 62 Driver source: 63 * wireless/ MSF source 64 * hcf/ HCF and F/W source 65 * wireless/wlags49_cs.mk Driver Makefile, PC Card 66 * wireless/wlags49_pci.mk Driver Makefile, PCI 67 * include/hcf/debug.h Driver debug support 68 * include/hcf/hcfcfg.h Header to configure HCF 69 * include/wireless/*.h Driver source headers 70 71 Driver online manual page: 72 * man/wlags49.4 Driver manual page 73 74 PCMCIA configuration update: 75 * etc/wlags49.conf Add-on config file 76 * etc/wlags49.mk config update Makefile 77 * etc/wlags49.patch config update patch file 78 79 The driver is build up of 2 modules: 80 - a higher module called Module Specific Functions (MSF), which contains 81 the functions of the driver that are network driver interface and 82 Operating System specific. 83 - a lower module called Hardware Control Functions (HCF), which contains 84 the functions to interface to the Network Interface Card (NIC). The HCF 85 provides for all WaveLAN NIC types one standard interface to the MSF. 86 This I/F is called the Wireless Connection Interface (WCI) and is the 87 subject of a separate document (025726). 88 89 The HCF directory contains firmware images to allow the card to operate in 90 either station (STA) or Access Point (AP) mode. In the build process, the 91 files fw_h2.c and fw_h25.c are used for Hermes-II and Hermes-II.5 92 respectively. The firmware images in this release are identified as: 93 - HII Station F/W: fw_h2.c.sta 94 - HII.5 Station F/W: fw_h25.c.sta 95 - HII AccesPoint F/W: fw_h2.c.ap 96 - HII.5 AccesPoint F/W: fw_h25.c.ap 97 To build a STA or AP mode driver, the suffix .sta or .ap must be removed. 98 The files as distributed by this release build STA drivers by default. 99 100------------------------------------------------------------------------------ 1012. SYSTEM REQUIREMENTS 102 1032.1 Operating System 104 105 This software can be compiled and installed with Linux kernel versions 106 2.4.x. Although this driver should compile for other CPUs as well, as of 107 the date of this release, no CPU architectures other than x86 have been 108 verified. 109 110 wl_lkm_7_22_abg is tested with the following Linux Distributions: 111 * Red Hat version 9.0 112 * Suse version 9.0 113 114 If you're building for PC Card or Compact Flash, you need the Card Services 115 from David Hinds. 116 117 wl_lkm_7_22_abg is tested with: 118 * pcmcia-cs-3.2.7.tar.gz 119 1202.2 Free Disk Space 121 122 To compile the software you need to have the full set of Linux kernel 123 source files installed, as well as a sane build environment which includes 124 all tools necessary for compiling and linking code. Depending on the exact 125 version of the kernel, you need approximately 150 MB of free disk space. 126 Once compiled, the driver uses about 150-200 KB. Please note, this size is 127 approximate and can vary depending on which version of the driver is built. 128 In addition, adding debug tracing support increases this size. 129 130------------------------------------------------------------------------------ 1313. NEW IN THIS RELEASE 132 133Version 7.22 abg - July 28, 2004 134 135------------------------------------------------------------------------------ 1364. INSTALLATION NOTES 137 138 The driver files for the Linux driver are not "ready" for direct 139 installation onto any Linux computer. To build and install the driver you 140 need some expertise on the Linux operating system in general and the type 141 and version installed of the kernel installed on your computer. With this 142 knowledge you can use the driver source files provided to build your own 143 Linux driver for your specific computer and kernel. 144 1454.1 Before you start 146 147 1) Determine the type and version of the Linux kernel of your computer and 148 check whether it meets the system requirements listed in section 2 of this 149 README. 150 151 2) If you're building for PC Card or Compact Flash, read the Linux 152 PCMCIA-HOWTO by David Hinds. This document is probably provided on the 153 CD-ROM of your Linux distribution. You can download the latest version 154 from: 155 156 http://pcmcia-cs.sourceforge.net 157 158 Please read the section titled "Prerequisites and kernel setup" of the 159 PCMCIA-HOWTO. 160 1614.2 Build the driver for PC Card / Compact Flash 162 163 1) Obtain a copy of the Linux PCMCIA package from a CD-ROM of your Linux 164 distribution or download the latest version. 165 For your convenience, the Agere Systems Wireless CD-ROM contains a copy of 166 the PCMCIA package in sub-directory: Xtras/Linux/PCMCIA 167 168 2) To unpack the Linux PCMCIA package, copy it to the current working 169 directory and type: 170 % tar xzvf pcmcia-cs-x.y.z.tar.gz 171 % mv pcmcia-cs-x.y.z pcmcia-cs 172 173 Note: If you use the archive supplied on the CDROM, use archive name 174 "pc3_2_1.tgz" instead of "pcmcia-cs-3.2.7.tar.gz". 175 176 Note: even though PCMCIA code exists in the kernel source tree, the PCMCIA 177 Card Services package needs to be unpacked locally to build drivers based 178 on it. 179 180 3) Extract the wlags49 distribution archive on top of the Linux PCMCIA 181 package. 182 % cd pcmcia-cs 183 % tar xzvf ../wl_lkm_7_22_abg.tar.gz 184 185 4) To build and install the driver, follow the procedure below: 186 % ./Configure 187 188 Answer the presented questions. Usually the default answers are OK and 189 pressing "Enter" is enough. 190 On newer RedHat systems, however, you should specify "/usr/src/linux-2.4" 191 as the Linux source directory instead of the default "/usr/src/linux". 192 193 For more detailed information on configuration, building and installing, 194 see the PCMCIA-HOWTO. 195 196 To build the default drivers, which support Hermes-II in station mode, run 197 the Build script: 198 % ./Build 199 200 This script determines whether your system uses in-kernel PCMCIA and either 201 builds the full PCMCIA package or just the driver. 202 203 Before installing the driver with the Install script, you must become 204 'root': 205 % su 206 .. 207 % ./Install 208 209 This script determines whether your system uses in-kernel PCMCIA and either 210 installs the full PCMCIA package or just the driver. 211 212 5) If it becomes necessary to clean the build, issue the following 213 commands: 214 % make clean 215 % make -C lib clean 216 2174.3 Build the driver for PCI 218 219 1) Extract the wlags49 to the current working directory. 220 % tar xzvf wl_lkm_7_22.tar.gz 221 222 Note: there is no need to unpack the driver source into a PCMCIA build 223 directory. 224 225 2) To build the PCI driver: 226 % make -f wlags49.mk wlags49_h2_pci 227 or 228 % make -f wlags49.mk wlags49_h25_pci 229 230 3) Install the driver. 231 % insmod ./wireless/wlags49_h25.o 232 233 4) If it becomes necessary to clean the build. 234 % make -f wlags49.mk pci_clean 235 2364.4 Configure your Wireless PC Card 237 238 There are 3 ways to configure the driver 239 - module parameters (/etc/pcmcia/config.opts) 240 - wireless extension (/etc/pcmcia/wireless.opts) 241 - Agere configuration file (/etc/agere/iwconfig-eth#) 242 243 2444.4.1 Configure through /etc/pcmcia/config.opts 245 246 To use this method, make sure that /etc/pcmcia/wireless.opts file is either 247 absent or contains blank parameter values as shown below. 248 249 *,*,*,00:60:1D:*|*,*,*,00:02:2D:*) 250 INFO="" 251 ESSID="" 252 MODE="" 253 KEY="" 254 ;; 255 256 1) To configure the Wireless PC Card, please refer to: 257 * The online manual page (wlags49.4) 258 % man wlags49 259 * The network adapter sections of the PCMCIA documentation. 260 % more PCMCIA-HOWTO 261 262 2) Use an editor to configure the module parameters: 263 # vi /etc/pcmcia/config.opts 264 265 a) To connect your computer to a wireless infrastructure that includes 266 access points such as the AP-1000 or AP-500, you need to identify the 267 network name of the wireless infrastructure. 268 269 For example if your infrastructure uses the network name "My Network", 270 edit the config.opts file to include the following: 271 272 module "<driver_name>" opts "network_name=My\ Network" 273 274 Notice that the space character needs to be escaped with a backslash. 275 276 b) To connect your computer to a Residential Gateway RG-1000, you need 277 to know the RG ID (=network_name) and the encryption key. You can find 278 the RG ID on a small label on the rear of the unit. 279 280 For example if your RG-1000 has ID 225ccf and you did not change the 281 encryption key yet, edit the config.opts file to include the following: 282 283 module "<driver_name>" opts "network_name=\"225ccf\" key_1=\"25ccf\" 284 enable_encryption=Y" 285 286 If you changed your encryption key, you should specify this key as key_1 287 on the parameter line. 288 289 c) To connect your computer to a peer-to-peer network, in an environment 290 without access points, the IBSS mode is recommended. 291 292 For example to connect to a peer-to-peer network called "My Network", 293 enter the following in the config.opts file: 294 295 module "<driver_name>" opts "create_ibss=Y network_name=My\ Network" 296 297 d) Optionally you can also include a "Station Name" value that can be 298 used to indentify your computer on the wireless network. 299 300 For example if you wish to name your computer "Wave1" when connecting it 301 to a wireless infrastructure, edit the config.opts file to include the 302 following: 303 304 module "<driver_name>" opts "network_name=Ocean station_name=Wave1" 305 306 e) To connect your computer to an Ad-Hoc workgroup of wireless 307 computers, enter the following in the config.opts file: 308 309 module "<driver_name>" opts "port_type=3" 310 311 Note that the "Ad-Hoc Demo Mode" is not the recommended mode for a 312 peer-to-peer network. The configuration of this non-interoperable mode 313 is only explained here for special applications (e.g. research, or 314 compatibility with other / previous WaveLAN/IEEE products). 315 316 The IBSS mode described in c) is the preferred and interoperable mode 317 for creating a peer-to-peer network. 318 319 3) Use an editor to modify the network options for your adapter. 320 # vi /etc/pcmcia/network.opts 321 322 The parameters need to be correct for the connected network. Check with 323 your system administrator for the correct network information. Refer to 324 the PCMCIA-HOWTO for more configuration information. 325 326 For example: 327 *,*,*,*) 328 IF_PORT="" 329 BOOTP="n" 330 IPADDR="10.0.0.5" 331 NETMASK="255.255.255.0" 332 NETWORK="10.0.0.0" 333 BROADCAST="10.0.0.255" 334 GATEWAY="10.0.0.1" 335 DOMAIN="domain.org" 336 DNS_1="dns1.domain.org" 337 ;; 338 339 RedHat and Suse do not use the network.opts to configure the driver. 340 Instead RedHat uses a GUI-based tool called 'neat' ('net.cfg' in older 341 versions) and SuSE Linux uses 'YaST'. These tools creates scripts, like 342 ifcfg-eth0, in the directory /etc/sysconfig/network-scripts. Using the 343 default GNOME menu, you can start netcfg from: Programs->System->Network 344 Configuration. 345 346 4) Restart the PCMCIA services. 347 # /etc/rc.d/rc.pcmcia restart 348 or 349 # /etc/rc.d/init.d/pcmcia restart 350 351 352 For a more detailed description about the various configuration options and 353 definitions, please consult the Wireless documentation. 354 3554.4.2 Configure through /etc/pcmcia/wireless.opts 356 357 This driver has support for the "Wireless Extensions". This interface 358 allows the "Wireless Tools" to get statistics from the driver and allows to 359 change the configuration of the driver on the fly. 360 361 The latest versions of the PCMCIA package contain scripts that use the 362 wireless extension to configure the driver as an alternative to the 363 configuration through module parameters as described in section 4.4.1. 364 Read the /etc/pcmcia/wireless.opts file for the theory of operation. When 365 the driver is configured, go to section 4.4.1 step 3 to configure the 366 network parameters. 367 368 For more information, refer to the following WEB pages: 369 http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Linux.Wireless.Extensions.html 370 http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html 371 3724.4.3 Configure through /etc/agere/iwconfig-eth# 373 374 In addition to using either the module options or the wireless extensions 375 methods to configure a wireless device, this version of the software also 376 supports an Agere specific implementation. This was done because: 377 * Module options configures multiple devices the same. 378 * Wireless extensions parameters do not cover all of the available options 379 in the driver. 380 381 For each wireless ethernet device (identified by eth<n>, where n is a 382 positive integer), a file /etc/agere/iwconfig-eth<n> can be created which 383 contains configuration information for a wireless device. For example, the 384 file /etc/agere/iwconfig-eth1 is the config file for eth1. This file should 385 contain Key/Value pairs in the format: 386 387 <Key>=<Value> 388 389 where <Key> is the parameter to configure and <Value> is the value to 390 assign it. For example, if the config file /etc/agere/iwconfig-eth1 391 described above contains the following: 392 393 DesiredSSID=some_network 394 EnableEncryption=Y 395 Key1=net01 396 TxKey=1 397 398 this configures eth1 to associate to the ESSID 'some_network' with 399 encryption on, where the the first encryption key is 'net01' and the key to 400 use for encryption is Key 1. 401 402 Note that this only works on Agere hardware which uses this driver. For 403 other wireless drivers, or non-wireless devices, this file can be present, 404 but has no effect. 405 406 Please refer to the man page for more information on this configuration 407 file and the parameters that can be set. 408 409 4104.5 Configuring your Wireless PCI card 411 412 Note that the above method of configuring the card using 413 /etc/pcmcia/config.opts is only valid for PCMCIA/CF cards. For [mini]PCI 414 and CardBus cards, refer to your system's documentation on modules.conf to 415 load the driver with the proper options for a given wireless ethernet 416 interface. In addition, network configuration tools like 'netcfg', 'neat', 417 or 'YaST' (see Section 4.4.1, Step 3) can be used to configure the miniPCI 418 card. Lastly, the Agere configuration file described in Section 4.4.3 may 419 also be used for [mini]PCI and CardBus devices. 420 4214.6 Troubleshooting 422 423 When the Wireless PC Card is inserted, the card manager emit beeps in 424 different tones to indicate success or failure of particular configuration 425 steps. 426 a) Two high beeps 427 - The card was identified and configured successfully. 428 b) One high beep followed by a low beep 429 - The card was identified, but could not be configured. 430 - Examine the system log (dmesg) for PCMCIA error or warning messages. 431 c) One low beep 432 - The card could not be identified. 433 - Execute "cardctl ident" to display the adapter PnP information. 434 Verify the PnP information matches an entry in the PCMCIA 435 configuration file (/etc/pcmcia/config). 436 - Examine the system log (dmesg) for PCMCIA error or warning messages. 437 438 The Wireless PC Card has two LEDs that indicate the state of the adapter 439 and network. 440 * Power LED (toward the middle of the adapter) 441 - This LED indicates power has been applied, and the card is 442 functional. In normal operation mode with Card Power Management 443 disabled, it is steady-on. With Card Power Management enabled, it 444 blinks rapidly (several times per second). 445 * Transmit/Receive LED (closer to the edge of the adapter) 446 - This LED flashes when it detects transmit or receive packets. 447 448 * Both LEDs blink at the same time every 10 seconds. 449 - The adapter was unable to make contact with the named wireless 450 network. Verify the network_name, in the config.opts file matches the 451 network name of the access point. 452 * LEDs indicate normal operation with the Power LED 453 steady-on or blinking rapidly and Transmit/Receive LED flashing, but no 454 traffic. 455 - If the network is operating in normal mode (ie. port_type = 0 or not 456 specified), and a network_name has been specified, verify the 457 workstation network parameters (ifconfig, route, etc.) are correct 458 for the wireless network. 459 - If the network is operating in Ad-Hoc (peer-to-peer) mode (ie. 460 port_type = 3), the adapter needs another workstation/adapter to 461 communicate with. Verify the network parameters on both of the 462 workstations (ifconfig, route, etc.) are correct. 463 464 Refer to the online manual page for additional configuration, feature and 465 support information. 466 % man wlags49 467 or 468 % man 4 wlags49 469 or 470 % nroff -man wlags49.4 | more 471 4724.7 Identifying the software 473 474 This section explains how to identify the version of this software once it 475 is unpacked or installed. 476 477 The Linux Driver Source/Library distribution consist of two main 478 components, the driver source and the HCF module. 479 480 * To quickly identify the version of the source, type: 481 % grep DRV.*VERSION include/wireless/wl_version.h 482 #define DRV_MAJOR_VERSION 7 483 #define DRV_MINOR_VERSION 22 484 485 * To identify the revision of the HCF library contained in the driver, 486 type: 487 % grep HCF.Revision hcf/hcf.c 488 #define HCF_VERSION TEXT( "HCF$Revision: 1.8 $" ) 489 490 To identify a compiled wlags49 driver, go to the directory where the driver 491 is located. Card Services drivers (wlags49_h2_cs.o and wlags49_h25_cs.o) 492 are located in: 493 /lib/modules/<kernel-version>/pcmcia 494 495 PCI drivers (wlags49_h2.o) are located in: 496 /lib/modules/<kernel-version>/kernel/drivers/net 497 498 * To retrieve the version of the source used to compile the driver, type: 499 % strings <driver_name>.o | grep Agere 500 <driver_name> v7.22-abg-Beta for PCMCIA 501 <driver_name> v7.22-abg-Beta for PCI 502 503 * Likewise, to retrieve the revision of the HCF used to compile the driver, 504 type: 505 % strings <driver_name>.o | grep Revision 506 HCF$Revision: 5.15 507 508 At startup the wlags49 driver reports its version in the system log file 509 (/var/log/messages). 510 511------------------------------------------------------------------------------ 5125. TECHNICAL CONSTRAINTS 513 514 At the time of release of this software, the following constraints are 515 identified: 516 5175.1 Using the ISA adapter 518 519 Description: To allow operation in desktop computers Agere also provides an 520 optional ISA bus to PC Card adapter (also referred to as "swapbox"). 521 522 This ISA Adapter can be configured for two different I/O Address values: 523 * 3E2 (factory-set default) 524 * 3E0 525 526 Impact: By default the i82365 module of the Linux pcmcia package only 527 probes at 3E0. 528 529 Actions: 530 1) Read the manual page on the probing of the i82365 module, by typing the 531 command: 532 man i82365 533 534 2) Apply one of the two following options: 535 a) Change the I/O address strapping of the ISA adapter by replacing the 536 jumper on the ISA adapter. The correct jumper setting is pictured in 537 the electronic "Wireless ISA Adapter, Getting Started Guide" provided 538 on the Wireless Software CD-ROM. This guide is provided in Adobe's 539 Acrobat PDF format. 540 541 b) Alternatively, you can load the i82365 module with the 542 "extra_sockets" parameter set to 1. 543 544 On a RedHat 5.x thru 7.x, system, put this in the file 545 "/etc/sysconfig/pcmcia": 546 PCMCIA=yes 547 PCIC=i82365 548 PCIC_OPTS="extra_sockets=1" 549 CORE_OPTS= 550 CARDMGR_OPTS= 551 552 For other Linux distributions, you are advised to consult the 553 "PCMCIA-HOWTO" notes for information about changing the I/O Address 554 probing. 555 5565.2 Using the PCI Adapter 557 558 Description: To allow operation in desktop computers Agere also provides an 559 optional PCI bus to PC Card adapter (also referred to as "swapbox"). 560 561 For correct interrupt assignment, the system should support PCIBIOS 2.2. 562 It is recommended to use PCMCIA package version 3.2.7 or higher. 563 564 The default configuration of the interrupt routing method of the PCI 565 Adapter's TI CardBus Controller is incorrect. 566 567 Actions: 568 1) Read the manual page on the "Options specific for TI CardBus 569 Controllers" of the i82365 module, by typing the command: 570 man i82365 571 572 2) Load the i82365 module with the "irq_mode" parameter set to 0. 573 On a RedHat 5.x thru 7.x system, put this in the file 574 "/etc/sysconfig/pcmcia": 575 PCMCIA=yes 576 PCIC=i82365 577 PCIC_OPTS="irq_mode=0" 578 CORE_OPTS= 579 CARDMGR_OPTS= 580 581 For the location of the PCMCIA scripts on other Linux distributions, you 582 are advised to consult the "PCMCIA-HOWTO", "Notes about specific Linux 583 distributions". 584 585------------------------------------------------------------------------------ 5866. KNOWN ISSUES 587 588 This is the current list of known issues for this release, and will be 589 addressed in the near future: 590 591 1. This driver release contains a version of Hermes-II.5 firmware which 592 REQUIRES calibrated cards. If there is no calibration data present in the 593 PDA of the hardware, the firmware does not operate. 594 595 2. WDS is not yet supported. 596 597 3. DMA is not yet supported. 598 599 4. WPA is not yet supported. 600 601 5. 32-bits I/O is not yet supported. 602 603 6. The current Build script also builds the PCI drivers. 604 605 7. The current Install script also copies the PCI drivers to the lib 606 directory. 607 608 8. If F/W files are required from outside this release, the entry points 609 inside these F/W files have to be renamed from "ap" and "station" to 610 "fw_image" and they have to be renamed to fw_h2.c and fw_h25.c for 611 Hermes-II and Hermes-II.5. 612 613------------------------------------------------------------------------------ 6147. TECHNICAL SUPPORT 615 6167.1 Finding Information 617 618 On the Agere Systems Web Site you can find the most recent device drivers, 619 software updates and user documentation. 620 621 World Wide Web: http://www.agere.com 622 6237.2 Contact Technical Support 624 625 If you encounter problems when installing or using this product, or would 626 like information about our other "Wireless" products, please contact your 627 local Authorized "Wireless" Reseller or Agere Systems sales office. 628 629 Addresses and telephone numbers of the Agere Systems sales offices are 630 listed on our Agere Systems web site. 631 632 When contacting Technical Support, please use the Problem Report Form and 633 send it to us by Fax or E-Mail. The Problem Report Form 'REPORT.TXT' 634 (Plain text format) is included on the disk. Alternatively, you can 635 download the Problem Report Form from the Agere Systems web site. 636 637 Include Product Name, Serial Number and software version number with each 638 request to help the Support Group helping you. 639 640============================================================================== 641 END OF FILE 642