          *********************************************
          iBurst compatible driver for Linux kernel 2.6
          *********************************************

iBurst (TM) compatible wireless modem driver
based on the original ArrayComm (TM) iBurst (TM) driver.

CREDITS
-------

David Michael Barr
* Ported USB code to 2.6 Linux kernel.

Nicholas Jefferson
* Rewrote driver for 2.4 Linux kernel.

Nik Trevallyn-Jones
* Organized project.
* Ported PCMCIA code to 2.6 Linux kernel.
* Wrote documentation.
* Contributed initial wireless extensions (iw_ioctl) code
  (based on orinoco driver - see credits in ib-net.c for details)
* Implemented changes for further new USB devices and chipsets.

Scott Mckenzie
* Contributed code for HAL/SYSFS integration

Greg Cockburn and Scott McKenzie
* Contributed code to support the new pcmciautils system

Shane MacPhillamy
* Contributed code to support new USB devices and chipsets.

Daniel Burr
* Contributed code to support changes in kernels 2.6.16
* Contributed code to support changes in kernels 2.6.20

Damian Ivereigh
* Contributed code to support changes in kernels 2.6.17

Ross Cameron
* Contributed a patch to support kernel 2.6.24 (and possibly earlier)

----------------------------------------------------------------------------
The authors would like to thank ArrayComm(R) for writing and releasing GPL
drivers for their hardware in the first place, and for their support for this
project, as well as support provided by Personal Broadband Australia (PBA),
Kyocera, and Independent Service Providers Australia (ISP).
-----------------------------------------------------------------------------

Overview
--------
The ibdrivers are supplied as source code, which has to be compiled and built
before you can use them. The process of building them is well automated, and
can be easily performed by novice users. Diagnosing any problems that may arise
can be more involved, so this document lists the more common problems and how
best to fix them.

Problems? There is a section at the end of this document which lists the more
	common problems and their resolution. In addition, community support is
	available on the SourceForge project forums at:

	http://http://sourceforge.net/forum/?group_id=138984

**Upgrade Notes: The file UPGRADE.txt contains additional notes to help you
  upgrade from the original ibut drivers to the ibdriver drivers. Since the
  ibut drivers are now more than a year old, it is highly unlikely that this
  will affect you.

Important Explanations:
-- The source code is compiled to create a driver which matches the particular
   kernel on your machine. You are very unlikely to have much success if you
   try using a driver compiled for a kernel different to the one you are
   using. (From point of view of a driver, kernel 2.6.13 is different to
   kernel 2.6.14 and 2.6.13 is different to 2.6.13smp.)
   The primary side-effect of this is that you will need to recompile and
   reinstall the driver after each kernel upgrade you perform.

-- Most linux distros are not shipped with the components required to build
   new modules. Installing the required extra components is usually quite
   straight forward. See the 'prerequisites' section of the instructions below
   for a full explanation and instructions.

-- Older kernels (depending on distro, prior to 2.6.15 or therabouts) require
   manual configuration for the iBurst hardware to be recognised. Later
   kernels automatically recognise the harware from information in the
   driver, and so need no configuration - just build the driver, connect the
   iBurst modem, and connect.

-- After module load, a dynamic network interface, typically called ib0, is 
   created automatically which provides an Ethernet interface for other network
   services to communicate with the iBurst device.
   ** This network device does *NOT* need to be configured, nor brought up**

-- The iBurst system uses PPPoE (Point-to-Point Protocol over Ethernet) to
   authenticate with the iBurst network. With PPPoE there are *always* two (2)
   network interfaces associated with the connection. One is the low-level
   ethernet interface used to communicate with the iBurst hardware (with
   ibdriver, this is typically called 'ib0'), and the second is the high-level
   interface used to create the connection to the internet (this is typically
   called ppp0).

-- Note that if your iBurst modem has an ethernet port on it, then you can
   plug it directly into your computer using an ethernet cable and connect
   using PPPoE without needing any driver. However, this uses up an ethernet
   port which may restrict your ability to share your iBurst connection.

-- A PPPoE dialler is required to connect to the iburst network. ibdriver
   does not come with a pppoe dialler. You can use the pppoe dialler that
   ships with your distro, or the Roaring Penguine GUI pppoe dialler
   (www.roaringpenguin.com/pppoe/), or other.

-- Details for configuring the more popular PPPoE diallers are included below,
   but in essence, the PPPoE interface (usually ppp0) must be configured to use
   the correct low-level interface (usually ib0), and the low-level interface
   must exist before the ppp* interface can be started. Since ibdriver creates
   the low-level interface automatically, all that is needed is that the iBurst
   hardware must have been successfully inserted/connected before the PPP
   connection can be started.

-- The PCMCIA driver does not support suspend/resume. You should unload the
   driver before suspending. See Appendix A1 for details.

-- While some simple scripts are provided to provide status and monitoring
   information, the driver now publishes information to the wireless extension
   subsystem, enabling existing wireless network tools to monitor devices
   using ibderiver.

The iburst driver has been tested on a number of 2.6 kernels including
Fedora Cores 3 to 8, Debian, Pclinuxos, SUSE, and others.
As of ibdriver 1.3.2, kernel revs up to 2.6.24 are known to be supported.

**For the impatient:
--------------------
   Here are the essential steps required to build and connect with the
   iBurst modem. If you have problems with any of these summary steps, read
   the more detailed information further on in this document.

   (i) ensure you have kernel development tools installed.
   (ii) extract the tarball, to somewhere useful, eg /tmp
   (iii) cd to the extractd directory and run 'make'
   (iv) as root, cd to the extracted directory and run 'make install'
   (v) perform any configuration for the driver to recognise the hardware
       (on newer kernels (> 2.6.15, depending on distro) no configuration
       is required.)
   (vi) connect your iBurst hardware and make sure it initialises correctly.
   (vii) configure a PPPoE dialler, and make sure it uses the ibdriver
         dynamic ethernet device.
   (viii) connect using your configured PPPoE interface.

**Notes:
--------
   [SMP kernels]
      The drivers work fine on SMP kernels, although some of the instructions
      in this document are slightly different for SMP.

      More recent kernels are both SMP and uniprocessor capable. However,
      earlier 2.6 kernels distinguished between uniprocessor and SMP.

      If you have a specific SMP linux kernel then that is different to a
      non-SMP kernel.  Therefore, if you are running an SMP kernel, you will
      need to build the drivers for that kernel, using the correct SMP kernel
      headers and development packages.

      To check, type the following command:

         $ uname -r

      If the kernel version string has 'smp' in it, then you are currently
      running an SMP kernel.

      Eg: 2.6.17-1.2187_FC5smp
   [/SMP Kernels]

   [Multiple CPU machines]
      This includes Hyper-Threaded CPUs, dual-core CPUs and multiple-CPU
      motherboards.

      To exploit multiple CPUs, you must be using an SMP-capable kernel.
      See the notes above and in various points below for SMP kernels.
   [/Multiple CPU machines]

   [ibdriver >= 1.2.6]
      In the initial release of ibdriver, the pcmcia poll period was defaulted
      to a value which limited throughput. The fix was to manually set the
      pcmcia 'interval' option to 20 (or less).

      As of ibdriver 1.2.6, the default value is sufficiently small (it is 10),
      so the option should not need to be changed until iBurst is capable of
      throughput over 1.5 Mbps.      
   [ibdriver >= 1.2.6]

   [ibdriver 1.3.1]
      In response the the growing mesh of kernel-dependent #if statements,
      the code was split into two variants: pre and post kernel 1.2.17.
      Versions with linux-2.6 as the suffix complile on kernels up to 2.6.16.
      Versions with more specific suffixes (eg linux-2.6.17) are specific
      to a range of versions up to the specified version.
   [/ibdriver 1.3.1]

   [Debian, Ubuntu]
     Debian Sarge (and possibly others) ships with a pppoe dialler that
     places particular requirements on the name of the network interface
     used by the iburst driver. To use the this debian pppoe dialler, you
     need to tell the iburst driver to use a network name of the form:
     "nas-ib%d" (or "eth%d") instead of the usual "ib%d". Instructions for
     configuring the debian pppoe dialler are in section 9.2 below.
   [/Debian]

   [Fedora Core (2 & 3)]
     Early versions of Fedora Core did not always pass the CORE_OPTS variable
     to the pcmcia_core module. On these distros, if pcmcia core needs options
     to work with the iBurst hardware, the options can be inserted into
     /etc/modprobe.conf, as an options line.
   [/Fedora Core]

   [Fedora Core 5]
     Recent Fedora Core 5 kernels now use the new pccard system, so there is
     no pcmcia config file to update.

     There have also been reports of the PCMCIA card failing to initialise
     when inserted. The current workaround is to 'insert' the card with
     software using the command (as root):

     $ pccardctl insert

     You may need to repeat this command 2 or 3 times.
   [/Fedora Core 5]

   [Kernel >= 2.6.13]
     A change in linux to the PCMCIA callback structure means that you must
     have ibdriver 1.2.6 or above (or apply the kernel 2.6.13 patch to ibdriver
     1.2.1) (patch supplied by Greg Cockburn - thanks Greg!).

     Some newer distros using kernel >= 2.6.13 also use a new pccard system in
     place of the pcmcia system. This new system has no pcmcia config file.
     Associations between cards and drivers are defined within the driver
     itself. Versions 1.2.8 and above of ibdriver has this definition built in
     for the Kyocera iBurst (TM) card.
   [/Kernel >= 2.6.13]

   [Kernel > 2.6.15]
     Changes in the PCMCIA subsystem at kernel 2.6.16 requires changes to
     the driver. There is a patch posted on the SourceForge site by
     Daniel Burr (thanks Daniel!).

     This patch has been incorporated into ibdriver 1.2.9
   [/Kernel > 2.6.15]

   [Kernel >= 2.6.17]
     Further changes in the kernel mean that 1.2 versions of the driver do not
     compile on this kernel. A patch has been posted on the sourceforge site
     by Damian Ivereigh (thanks Damian!).

     This patch is being incorporated into ibdriver 1.3 and above.
   [/Kernel >= 2.6.17]

   [Kernel >= 2.6.20]
     Changes in kernel 2.6.20 mean that ibdriver 1.3.1 and 1.3.2 do not compile
     on this kernel. A patch for ibdriver 1.3.1 has been posted on the
     sourceforge site by Daniel Burr (thanks Daniel!).
   [/Kernel >= 2.6.20]

   [Kernel >= 2.6.24]
     A small change in a network macro which all network device drivers use
     has meant an update was required,
   [/Kernel >= 2.6.24]

   [USB modem (UTU)]
     Patches have been made available to support the new USB modem (UTU) and
     other new hardware. Patches supplied by Shane MacPhillamy (thanks Shane!).

     These patches have been incorporated into ibdriver 1.2.9
   [/USB modem (UTU)]

   [Stats & monitoring]
     One particular difference between this linux driver and those for Windows
     and later MacOS was in the area of status and monitoring tools.
     A simple python script was provided with 1.2.8 and 1.2.9 which could
     display signal strength. However, such tools are naturally limited to
     particular windows managers, etc.

     Starting with ibdriver version 1.3.2, the driver now publishes information
     to the wireless extensions subsystem, meaning that any tool which can
     provide status or monitoring information for a wireless network device
     should be able to be used to monitor a device using the ibdriver.
     This code has been proven to work with command-line tools such as
     iwconfig, as well as KWireless and KWifiManager under KDE.
   [/Stats & monitoring]

To install the iburst drivers, and/or upgrade from the ibut drivers, follow
these steps:

0. Prerequisites
   On any linux system, you will need the correct components installed to
   be able to build new kernel modules. This includes compilers, linkers, system
   headers, and libraries. Distros differ in how they package this, but you
   will normally need to have installed a development package, and some form of
   kernel development package. With most 2.6 distros, the full linux source is
   *NOT* required.

   For example, Fedora calls the kerel development package 'kernel-devel',
   so to install it using yum, execute the following command (as root):

     $ yum install kernel-devel

   Similarly, if you have updated your kernel, then you will need to update
   the development package before you can successfully rebuild the driver.

     $ yum update kernel-devel

   The actual headers required to build drivers reside in a 'build'
   directory, in /lib/modules under a directory matching your kernel release.
   Eg: /lib/modules/2.6.15-1.2054_FC5smp/build

   [SMP kernel]
      The kernel development package for a specific SMP kernel is *different* to
      the kernel development package for a non-SMP kernel, and so has a
      different name. For example, Fedora names it 'kernel-smp-devel', so the
      command to install the SMP kernel development packages would be:

      $ yum install kernel-smp-devel

   [/SMP kernel]

   [Fedora Core 2 to 5]
      You can install the kernel development component using yum:

      $ yum install kernel-devel

      The kernel development component for SMP kernels is called
      kernel-smp-devel, so the command to install that would be:

      $ yum install kernel-smp-devel
   [/Fedora]

1. Build the modules:

-- Log in as root on a linux machine running kernel 2.6.x.
   -- On most 2.6 kernels, you should not need the full kernel source
      installed. The /lib/modules directory tree should contain everything
      needed to build a driver. On some distros, you will need to have
      installed the kernel-devel package in order to build new modules.

-- extract the tar file. A good place might be: /tmp

-- cd to where you extracted it, e.g.:   cd /tmp/ibdriver-x.y

-- Build the modules
     $ make

   If you get errors here, then you may not have the necessary
   components installed to build new modules. Check your distro information
   to find out what you need to install to build modules.

   If you do have the correct components installed and still get errors, then
   the most likely cause is that your kernel is newer than the newest kernel
   supported by the driver code. Please report any such errors to the
   sourceforge project (http://sourceforge.net/projects/ibdriver/).
   Often the changes are quite small, so it is worth seeing if you can change
   the source to get it to compile. If you succeed, please post a patch to
   the sourceforge project. We are happy to perform further quality-assurance
   on your code, so it needn't be perfect before you post it.
   A number of patches for newer kernels have been posted by users doing this.
   (Thank you again to all those who have helped the project in this way.)

   -- If you have a really good reason for doing so, you *can* specify a linux
   kernel version different to the one you are currently running.
   **Note** You must have installed the kernel-devel components for the kernel
   you are attempting to build for. Specifically, /lib/modules *must* contain a
   directory matching the kernel name, and that directory must contain a
   'build' subdirectory.

   The kernel version can be overridden using the IB_KERNEL_VERSION variable.
   Eg, to build for a 2.6.15 kernel on a machine running 2.6.17, you could
   proceed as follows:

     $ uname -r
     2.6.17-1.2187_FC5smp

     $ ls /lib/modules
     2.6.15-1.2054_FC5smp  2.6.17-1.2187_FC5smp

     $ make IB_KERNEL_VERSION=2.6.15-1.2054_FC5smp

-- Install the modules (you must be root to do this):
     $ make install

     -- Or, if you built for a version different to the running version:
     $ make IB_KERNEL_VERSION=<kernel-version> install

-- Should you wish to re-run the installation at any time,
   cd to the build directory and
     $ make clean; make; make install

-- To uninstall the files, make the uninstall target (you must be root):
     $ make uninstall

     -- Or $ make IB_KERNEL_VERSION=<kernel-version> uninstall

2. Configure the device

2a. Configuring the PCMCIA device
   The iburst pcmcia module is called "ib-pcmcia". It depends on a central
   module which is called "ib-net". If the configuration is correct, both
   drivers should load automatcially when needed, and unload when not needed.

  [Newer distros with kernel >= 2.6.13]
    **Note these instructions are for the older style pcmcia subsystem. Newer
      distros with kernels >= 2.6.13 may use the newer pccard system, which has
      no config file. If your system does not use/need a pcmcia config file,
      then you should skip this step.
  [/Newer distros]

-- Edit the pcmcia config file. This is usually called /etc/pcmcia/config.
   Insert the following lines. At the bottom is fine, but you may wish to
   order things as per the rest of the file which is alphabetically, per entry
   type. So you would put the "device" entry with the other "device" entries,
   in alphabetical order, and the the "card" entries with the other "card"
   entries.

   device "iburst_cs"
      class "network" module "ib-pcmcia"

   card "ArrayComm ut02"
      manfid 0x02e3, 0x0001
      bind "iburst_cs"

   card "ArrayComm ut02"
      manfid 0x02e3, 0x0002
      bind "iburst_cs"

  **Upgrade note: see UPGRADE.txt.

-- Edit the pcmcia parameters file. This is usually in
   /etc/sysconfig/pcmcia (others) or /etc/default/pcmcia (Debian).

     Add/modify the following line:

     CORE_OPTS="unreset_check=20 unreset_delay=100 unreset_limit=100"


-- Edit/create the appropriate modules configuration file.
   On older kernels, this was usually called /etc/modules.conf. On many 2.6
   kernels this is called /etc/modprobe.conf or /etc/modprobe.d/iburst.

   [Debian]
      Create /etc/modprobe.d/iburst, and insert the line:

      options ib-net ifname="nas-ib%d"

   [/Debian]

   [Ubuntu]
      **Note: Ubuntu is debian based, so the Debian instructiona above will
      probably work. However, the only report we have had used "eth" rather
      than "nas-ib".

      Create /etc/modprobe.d/iburst, and insert the line:

      options ib-net ifname="eth%d"

   [/Ubuntu]

   [Fedora Core (1, 2 & 3)]
      (Fedora Core doesn't always pass CORE_OPTS (above) to the pcmcia module,
      so the options are put into the modules config file as well.)

      Edit /etc/modprobe.conf and add these lines:

      # options for the core pcmcia module
      options pcmcia_core unreset_check=20 unreset_delay=100 unreset_limit=100

      #  alias for the iburst pcmcia driver
      alias iburst_cs ib-pcmcia

   [Fedora Core]

   [Others]
      Edit the modules configuration file and add the line:

      #  for the iburst pcmcia driver
      alias iburst_cs ib-pcmcia

   [/Others]

   [Some Installations]
      Usually the ib-net driver is loaded when a dependent driver, such as
      ib-pcmcia or ib-usb is loaded. Some installations may not load the ib-net
      driver automatically, in which case the following line in the modules
      config should help:

      Add the following line to the modules config file:

      alias ib0 ib-net

   [/Some Installations]


   [Other Parameters]
     The iburst drivers support the following module parameters, any of which
     can be set using an appropriate "options" line in the modules config
     file (/etc/modprobe.conf, etc).

     Example: options ib-pcmcia debug=7 interval=100

     ib-pcmcia
       - debug  values between 0 and 9, with 0 meaning disabled, and 9 meaning
         maximum output (default is 0).

       - io16   value is either 0 or 1, with 1 enabling 16-bit transfers
         to/from the card, and 0 meaning 32-bit transfers (default is 0).

       - interval  values between 10 and 1000, which specify the driver poll
         interval in milliseconds. Smaller settings will increase CPU usage of
         the driver (not normally a problem), and larger values will limit the
         maximum throughput. Eg, a value of 200 will typically limit throughput
         to around 180kbits/sec. (default 10).

       - irq_mask  values in hex, which specify, as a bit-mask, the irq
         interrupts to choose from (default is 0xdeb8 which corresponds to
         interrupts 15, 14, 12, 11, 10, 9, 7, 5, 4, and 3).

       - irq_list  a list of four integers, which specify the interrupts to
         choose from (default is not set).

     ib-net
       - debug  values between 0 and 9, with 0 meaning disabled, and 9 meaning
         maximum output (default is 0).

       - ifname  value is a string, which specifies the text part of the
         interface name to use (default is "ib%d").

     ib-usb
       - debug  value between 0 and 9, with 0 meaning disabled, and 9 meaning
         maximum output (default is 0).

   [/Other Parameters]


   **Upgrade note: see UPGRADE.txt

-- If you are not planning on rebooting, then you need to restart the pcmcia
   service to make it read the new configuration:

     $ service pcmcia restart

     or

     $ /etc/init.d/pcmcia restart


2b. Configuring the USB device
   Depending on distro, kernels arounf 2.6.15 no longer needed manual
   configuration of the USB system to recognise new hardware. So on a newer
   installation, no configuration of the USB sub-system is required.
   A simple test is to connect the USB device, check the logs to see that is
   has been recognised, and then perform lsmod to see if the ib-net and ib-usb
   drivers have been loaded. If not, then you may need to perform the
   configuration below.

   The iburst usb module is called "ib-usb". It depends on a central module
   called "ib-net". If the configuration is correct, both modules should load
   automatically when they are needed, and unload when they are not needed.

-- Add the following lines to /etc/hotplug/usb.usermap:

ib-usb 0x0003 0x0d14 0x0009 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000
ib-usb 0x0003 0x0482 0x0204 0x0000 0x0000 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000

-- If you are not planning on rebooting, then you need to restart the hotplug
   service with this command:

        $ service hotplug restart

        or

        $ /etc/init.d/hotplug restart

  [Fedora Core 3 (kernel 2.6.11-1.27_FC3, +others?)]
     hotplug is not a service, but is part of the kernel, so attempting to
     restart it (as above) will fail. In addition, hotplug does not load
     modules automatically from the definitions in usb.usermap (above).
     Instead, it attempts to run a script (in this case "ib-usb") in
     /etc/hotplug/usb. So you need to write it:

     -- Create /etc/hotplug/usb/ib-usb, and insert the following lines:

        #!/bin/sh
        modprobe ib-usb

     -- Make this file executable:
     $ chmod a+x ib-usb

   [/Fedora Core 3 (kernel 2.6.11-1.27_FC3)]


3. Insert/connect the device (PCMCIA or USB)
   It is a good idea to monitor the message log when inserting/connecting
   the device for the first (few) times (as root):

     $ tail -f /var/log/messages

   Insert/connect the device. watch the log for messages (good) or errors
   (bad).

3a. The PCMCIA device.
   The two lights should come on. The power light starts out purple(ish), and
   turns blue after a few seconds. If it does not turn blue, then the
   ib-pcmcia driver has not registered the card. Check the logs to see why.
   The activity light should change from orange to green (usually going
   through red). It then usually flickers a couple of times as it looks for
   the iBurst network.

3b. The USB device.
   The lights all come on when the device is plugged into the external
   power.


4. Set up the pppoe dialler to use the correct interface ("ib0" or "nas-ib0",
   etc), along with your user name and password. If you are using the
   roaring-penguin PPPoE package, you can use "adsl-setup" (as root).
   If you are using Debian, you can use the pppoe dialler that comes with that
   (see the separate instructions in section 4.1 for configuring debian's PPPoE
   dialer) or you can download and configure the roaring-penguin PPPoE dialer.
   Those users using the roaring-penguin dialler see the section 4.2 in this
   file for more details on configuring it.

 **Upgrade notes: see UPGRADE.txt

4.1 Configuring the Debian PPPoE dialler
-- Create /etc/ppp/peers/dsl-provider containing these lines:

        noipdefault
        usepeerdns
        defaultroute
        hide-password
        lcp-echo-interval 20
        lcp-echo-failure 3
        connect /bin/true
        noauth
        persist
        maxfail 0
        mtu 1492
        noaccomp
        default-asyncmap
        plugin rp-pppoe.so nas-ib0
        user "username@iburst.isp"

-- Add this line to /etc/ppp/pap-secrets:
        username@iburst.isp * password

-- Add these lines to /etc/network/interfaces:
        iface nas-ib0 inet manual
                up ifconfig $IFACE up
                up pon dsl-provider
                down poff dsl-provider
                down ifconfig $IFACE down


   You can manually start/stop the interface using:

     $ ifup nas-ib0

     and

     $ ifdown nas-ib0

4.2 Configuring the Roaring-Penguin PPPoE dialler

   The simplest way to configure roaring penguin PPPoE is with
   adsl-setup. Answer the questions, and all should be well:
      $ adsl-setup

   Most of the questions are straight forward. For the iburst driver, the
   Ethernet interface you want to use is "ib0" or "nas-ib0"
   (assuming you have setup a single card/modem).

   There are a number of ways of starting the connection. The most usual is to
   issue an ifup command on the ppp interface:
      $ ifup ppp0

   And use ifdown to stop the connection:
      $ ifdown ppp0

   On some distros, it appears that the ifdown command does not properly shut
   the connection down. If you find there are pppd or similar processes
   remaining after an "ifdown ppp0" that should not be there, then your distro
   may have this problem. In this case, try using adsl-start/adsl-stop
   instead.

   The roaring Penguin PPPoE dialler supplies start and stop scripts. To
   start the connection, issue:
      $ adsl-start

   This will start up the first ppp interface configured using adsl-setup.
   If you have more than one ppp interface, you can specify the one you want on
   the adsl-start command line:
      $ adsl-start <path-to>/ifcfg-ppp0

   To disconnect again, you can use the adsl-stop command:
      $ adsl-stop

   or
      $ adsl-stop <path-to>/ifcfg-ppp0


   **Note:
   Some people have found that regardless of the value specified to adsl-setup
   regarding on-demand startup and timeout, adsl-setup seems to configure the
   interface with an excessively short timeout value. See point 5.6 below for
   more details.

   Below is what a successful connection looks like:

   localhost pppd[6801]: pppd 2.4.2 started by root, uid 0
   localhost pppd[6801]: Using interface ppp0
   localhost pppd[6801]: Connect: ppp0 <--> /dev/pts/8
   localhost pppoe[6802]: PPP session is 2
   localhost pppd[6801]: CHAP authentication succeeded
   localhost pppd[6801]: local  IP address XXX.YYY.ZZZ.WWW
   localhost pppd[6801]: remote IP address AAA.BBB.CCC.DDD
   localhost pppd[6801]: primary   DNS address GGG.HHH.III.JJJ
   localhost pppd[6801]: secondary DNS address KKK.LLL.MMM.NNN
   localhost NET: /etc/sysconfig/network-scripts/ifup-post : updated /etc/resolv.conf

   If the startup gets stuck in a fairly tight loop failing to connect, try
   killing the connection attempt, and trying again.


5.  What can go wrong?
    A few things. Here is a summary of the well-known ones, and what to do to
    sort out why:

5.1 Building the drivers

5.1a Error message: /lib/modules/x.y.z/build: No such file or directory
    This indicates that the components required to build modules have not been
    installed/updated.
    
    - If this is the first time you have attempted to build a module,
      then find out what components are required to build modules, and install
      those. (Eg kernel-devel.)

         example fix (check for your distro):
	 $yum install kernel-devel

    - If you have just upgraded your kernel, then you probably need to update
      the components required to build modules as well. (Eg kernel-devel.)

         example fix (check for your distro):
	 $yum update kernel-devel


5.2 Checking the hardware status.
    Confirm the hardware has been recognised.

5.2a PCMCIA
     Use the cardctl command to show what hardware is currently recognised
     as being inserted:

       $ cardctl ident

       or, for the newer pccard systems:

       $ pccardctl ident

     Make sure your iBurst pcmcia card is listed, and compare the manfid
     values to those you entered into the pcmcia config (step 2).

     If the card does not show up when it is inserted, make sure pcmcia is
     configured and started on your machine. Check the logs and dmesg, looking
     for output from pcmcia and the kernel regarding pcmcia.

     If you see the error: "cs: pcmcia_socket0: time out after reset.", and
     cannot fix it in the configuration, try generating an insert event by
     executing the following command (as root):

        $ pccardctl insert

     You may need to repeat this command 2 or 3 times.

     If pcmcia is definitely working, and the card is still not being
     recognised, try testing the hardware to make sure it is not defective.

     If the card shows up, but the manfid differs to that in your config, try
     changing your config to match the card.


5.2b USB
     Use the lsusb command to show what hardware us currently recognised as
     being attached:

       $ lsusb

     Make sure your iBurst modem is listed, and compare the identifiers to
     those you entered into the config (step 2).

     If the modem does not show up when it is attached, make sure usb is
     installed and configured on your machine. Check the logs and dmesg,
     looking for output from usb and the kernel regarding usb. If usb is
     definitely working, and the modem is still not being detected, try
     testing the hardware to make sure it isn't defective.

     If the modem shows up, but the identifiers differ to what you've
     configured, try changing your config to match the modem.


5.3 Confirm the iburst drivers have recognised the hardware.
    The ib-net driver creates an entry in the /proc/driver tree.

    $ cat /proc/driver/iburst
    There is one, single-line entry per recognised device. Each entry shows
    the MAC address of the device.
    Eg: 00:10:E2:04:00:31

    $ ifconfig ib0
    Output looks like (partial):
            ib0   Link encap:Ethernet  HWaddr XX:YY:ZZ:AA:BB:CC
                  BROADCAST NOARP DYNAMIC  MTU:1500  Metric:1
                  RX packets:494 errors:0 dropped:0 overruns:0 frame:0
                  TX packets:9806 errors:0 dropped:0 overruns:0 carrier:0
                  collisions:0 txqueuelen:20
                  RX bytes:4030 (3.9 Kb)  TX bytes:78448 (76.6 Kb)

    Explanation:
        This lists network devices registered to the system;
        those entries beginning with "ib" (or "nas-ib", with debian pppoe) are
        iburst interfaces. The digit(s) at the end of the interface name
        correspond to the entries in /proc/driver/iburst. If the corresponding
        entry in /proc/driver/iburst does not match the HWaddr entry in
        ifconfig, then the drivers have not recognised your device correctly.
        Check your log file or load the module manually to find out why.

    [ibdriver >= 1.3.2]
       As of version 1.3.2, ibdriver publishes information to the linux
       wireless extensions.

       $ iwconfig ib0
       Output looks like:
	  ib0    HC-SDMA (iBurst)  Bit Rate:0.112 kb/s
		 Link Quality:100/100  Signal level:100/100  Noise level:0/100
		 Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
		 Tx excessive retries:0  Invalid misc:0   Missed beacon:0
      
    [/ibdriver >= 1.3.2]

5.3.1 Confirm modules have loaded correctly.
      **Note: The names of the modules on disk are ib-* whereas the name they
      report to the kernel are ib_*.

      Insert your device, and then check to ensure the correct modules have
      loaded:

        $ lsmod | grep ib_

      If the ib-net driver has not loaded, then dependent drivers including
      ib-pcmcia and ib_usb will not load correctly, and will report missing
      symbols (from the ib-net driver). Make sure the ib-net driver has loaded
      correctly before trying to diagnose errors with dependent drivers.

      **Note: misspelled driver options will typically stop a driver from
      loading. If a driver fails to load, and no other reason can be
      determined, try commenting out all "options" lines for the driver, and
      loading the driver again. If this works, check each value in the
      "options" line for typing mistakes.

5.3.1a PCMCIA:
       You should see ib-net and ib-pcmcia are loaded.
       If not, load them manually, to find out why.

       $ modprobe ib-net
       $ modprobe ib-pcmcia

5.3.1b USB
       You should see ib-net and ib-usb are loaded.
       If not, load them manually, to find out why.

       $ modprobe ib-net
       $ modprobe ib-usb


5.3.2 /proc/driver/iburst does not exist.
      The ib-net module did not load. Check your log file, or load the module
      manually to find out why.

5.3.3 ib0 (or nas-ib0) interface is not found.
      The ib-net module has not created the interface properly.
      Possible causes include incorrect configuration, or module(s) failing to
      load.

      - Check your configuration to ensure the interface name is correct and
        consistent

      - Check the log file or load the modules manually to see if there are any
        errors (see 5.3 above)


5.4 Error message: "unrecognised option" when loading the ib-pcmcia module.
    Check the spelling of the CORE_OPTS and/or pcmcia_core options.


5.5 Error message:
    "cs: socket <abc> timed out during reset.  Try increasing setup_delay."

    This error is usually accompanied by both lights on the card going off
    1-2 seconds after insertion.

    The pcmcia core is timing out before the iburst card has initialised.
    This can be fixed by passing some options to pcmcia_core on startup.
    The usual problem is misspelled options, or options that are not being
    passed to the pcmcia_core module. For example, Fedora Core doesn't always
    pass CORE_OPTS to the pcmcia module.

    If you added options to CORE_OPTS (step 2 above), check them for
    typos, and make sure the pcmcia module has been unloaded and reloaded. If
    this error continues, add the following line to your modules config file:

    "options pcmcia_core unreset_delay=100 unreset_check=20 unreset_limit=100"

    The option that specifically fixes this problem is the "unreset_limit"
    option. (That's correct, adjusting "setup_delay" doesn't actually fix the
    problem).

    If you continue to get this error after doing all the above, then the
    pcmcia module is probably not being reloaded, so try a reboot.

5.5.1 Error message:
    "cs: pcmcia_socket0: time out after reset."

    This error is usually accompanied by both lights on the card going off
    1-2 seconds after insertion.

    If this is on a kernel >= 2.6.17, we have not yet found a configuration
    that fixes this automatically. The current manual workaround is to 'insert'
    the card through software by executing the following command (as root):

       $ pccardctl insert

    You may have to repeat the command 2 or 3 times before the card initialises
    correctly.

5.6 Error message:
    "Inactivity timeout... something wicked happened on session XX"
    The connection is being closed due to a timeout. You can try adjusting the
    PPPOE_TIMEOUT parameter in the PPP config file. Eg:
    edit /etc/sysconfig/network-scripts/ifcfg-ppp0 (may be somewhere else in
    your distro - you may also try using the GUI admin tools to adjust the
    parameters of ppp0).

    Change PPPOE_TIMEOUT="xx" to some larger value, eg PPPOE_TIMEOUT="3600"
    should increase the timout period to 1 hour. Setting PPPOE_TIMEOUT to a
    value of zero (eg PPPOE_TIMEOUT=0) should disable the timeout altogether.


5.7 Checking the logs.
    If all is working as it should, there are no spurious errors in the log.
    All errors should be treated as a sign that something is wrong.

5.7.1 Error message:
    localhost wait_for_sysfs[xyz]: either wait_for_sysfs (udev abc) needs an
    update to handle the device '/class/net/nas-ib0' properly
    (no device symlink) or the sysfs-support of your device's driver needs to
    be fixed, please report to <linux-hotplug-devel@lists.sourceforge.net>

    Updating udev normally fixes this error. Beware of simply downloading and
    building the very latest udev - it is probably better to get a version
    built for your release. For example, at the time of this writing, the
    latest udev version is 057, and Fedora Core 3 ships with 039. Updating
    manually to version 057 resulted in errors that made X unusable, whereas
    installing the Fedora update to 039-10 fixed the problem. Using an update
    program is probably a very good approach, eg: "$ yum update udev".


5.7.2 Error message(s)
    localhost cardmgr[xxx]: socket 0: ArrayComm ut02
    localhost kernel: ib-pcmcia: Unknown parameter `'

    Some recent edit has probably left one or more spaces at the end of an
    "options" lines in your file. Edit yout modules config file and delete any
    trailing spaces from all lines.

    Possibly, you've removed a value from an "options" line in the modules
    configuration file, or perhaps had some other module installed since you
    installed the iburst driver, possibly by kudzu, or some other automated
    tool which has added one or more entries to the module configuration
    (/etc/modprobe.conf or /etc/modules, etc).

6. Cleaning up
Once everything is working smoothly, you should disable any debug output.

6.1 Edit the modules config file (eg /etc/modprobe.conf) and remove any
    "debug=" string from the "options ib-pcmcia" and/or "options ib-usb"
    line(s) (if it is present).


Appendices

A1. Suspend/Resume
  The pcmcia driver (ib-pcmcia) correctly suspends and resumes. However, the
  ib0 network interface is not correctly reinitialising. So currently, if
  you wish to suspend the machine, you should disconnect the pppoe connection,
  and eject the iburst card. Once you have resumed, re-insert the card and
  re-connect.

  It is expected that a future release will support suspend/resume without
  needing to eject and reinsert the card.


-------------------------------------------------------------------------------
* "ArrayComm" is a registered trademark of ArrayComm inc.
* "Iburst" is a tradmark of ArrayComm inc.
* "PBA" and "Personal Broadband Australia" are trademarks of Personal Broadband
   Australia.
-------------------------------------------------------------------------------
