          *********************************************
          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 <xanthophile@gmail.com>
D3D3 3BDA 26CF 75C4 FF91 387D 6708 0306 6CA8 086C
* Rewrote driver for 2.4 Linux kernel.

Nik Trevallyn-Jones
* Organized project.
* Ported PCMCIA code to 2.6 Linux kernel.
* Wrote documentation.

----------------------------------------------------------------------------
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 support provided by Personal Broadband Australia
(PBA), and Independent Service Providers Australia (ISP).
-----------------------------------------------------------------------------

**Upgrade Notes: This README contains additional notes to help you upgrade from
  the original ibut drivers.

  - You can (and it is probably a good idea to) keep your ibut configuration
    while you get the new iburst installation working. In the unlikely event
    that you encounter a problem, you can easily revert to the ibut driver
    until you have sorted things out.


The iburst driver has been tested on a number of 2.6 kernels including
Fedora Core 3, Debian, Pclinuxos, and others.

   [Debian]
     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" instead of the usual "ib". 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_OPS 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]


Notes:
-- The source code allows the driver be compiled to match the particular
   kernel on your machine.

-- After module load a network interface, typically called ib0, is created
   which provides an Ethernet interface for the iBurst devices to establish
   connection to the network.

-- A PPPoE dialler is required to connect to the iburst network. This driver
   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.

-- The PCMCIA driver has been tested with suspend/resume, with reasonable
   success. See Appendix A1 for details.

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

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.

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

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

-- Build the modules
     $ make

-- Install the modules (you must be root to do this):
     $ make 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


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.

-- 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. This 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 notes:
   - You can leave the ibut "device" entry (device "ibut_cs") intact, since
     it doesn't conflict with the iburst_cs entry.

   - You can comment out the ibut "bind" lines (bind "ibut_cs") and insert
     the iburst "bind" lines in their place. To change back to ibut, just
     comment out the iburst lines, and uncomment the ibut lines.
     Eg:
     card "ArrayComm ut02"
       manfid 0x02e3, 0x0001
       # bind "ibut_cs"
       bind "iburst_cs"

     If you don't comment out the ibut lines, make sure you have deleted them,
     otherwise they will conflict with the iburst binding.

-- 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 (eg Fedora Core 2 & 3) or
   /etc/modprobe.d/iburst (Debian), etc.

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

      options ib-net iface="nas-ib"

   [/Debian]


   [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 appripriate "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 (default 200).

       - 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").

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

   [/Other Parameters]


   **Upgrade notes
    - The default module configuration for ibut uses different module and
      interface names to the iburst driver and so don't conflict. So unless
      you have non-standard interface names that conflict, you can leave
      the ibut module configuration without change.


-- 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
   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+rx 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"),
   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:
  - Presumably, you already have a pppoe connection set up. All you need to
    do is change the device from "ibut0" to whatever your iburst interface
    name is ("ib0" or "nas-ib0").

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" (assuming you have setup a
   single card/modem).

   There are a number of ways of starting the connection. The best way appears
   to be the adsl-start command:
      $ 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, use the adsl-stop command:
      $ adsl-stop

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

   You can also issue an ifup command on the ppp interface:
      $ ifup ppp0

   However, on some distros, it appears that the corresponding ifdown command
   does not properly shut the connection down:
      $ ifdown ppp0

   If you find there are pppd or similar processes remaining after an ifdown
   that should not be there, then your distro may have this problem.
   Use adsl-start/adsl-stop instead.

   Some people have also 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.5 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 adsl-start gets stuck in a fairly tight loop failing to connect, try
   killing the connection attempt with adsl-stop, 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 Checking the hardware status.
    Confirm the hardware has been recognised.

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

       $ cardctl 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 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.1b 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. Cheack 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.2 Confirm the iburst drivers have recognised the hardware.
    The ib-net driver creates an entry in the /proc/drivers tree.

    $ cat /proc/drivers/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 00:10:E2:04:00:31
                  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:
        These list network devices registered to the system;
        those 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.

5.2.1 Confirm modules have loaded correctly.
      Insert your device, and then check to ensure the correct modules have
      loaded:

        $ lsmod | grep ib-

5.2.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.2.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.2.2 /proc/drivers/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.2.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.3 Error message: "unrecognised option" when loading the ib-pcmcia module.
    Check the spelling of the CORE_OPTS and/or pcmcia_core options.


5.4 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 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.6 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.6.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.6.2 error message(s)
    localhost cardmgr[3445]: socket 0: ArrayComm ut02
    localhost kernel: ib-pcmcia: Unknown parameter `'

    You've probably 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). The script or some other edit
    has left one or more spaces at the end of the "options" lines in your file.
    Edit yout modules config file and delete any trailing spaces from all
    lines.


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

12.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).

12.2 Once you are happy with the iburst driver installation, you may wish to
     remove the ibut configuration (see point 2 for details on the files for
     your distro)

-- Edit the pcmcia config file (refer to point 2a for details on this file).

   - Remove following entry from the pcmcia config file 

      device "ibut_cs"
         class "other" module "ibut_cs"

   - Remove the ibut bindings for the ArrayComm card(s):

      # bind ibut_cs

-- Edit the modules config file, and remove the following lines (if present):

      alias ibut_cs ibutPcmcia

      install ibutPcmcia /sbin/modprobe ibutBase && /sbin/modprobe --ignore-install ibutPcmcia && /sbin/modprobe ibutNet
      remove ibutPcmcia /sbin/modprobe -r ibutNet && /sbin/modprobe -r --ignore-remove ibutPcmcia && /sbin/modprobe -r ibutBase

      options ibutPcmcia ibutPcmciaDebugLevel=9 ibutPcmciaPollPeriod=20
      options ibutBase ibutNModems=1 ibutPreInit=1

      alias ibut0 ibutNet
      options ibutNet ibutNetworkName=ibut
      install ibut0 /sbin/modprobe --ignore-install ibut0 && /sbin/ifconfig ibut0 up arp
      remove ibut0 /sbin/ifconfig ibut0 down && /sbin/modprobe -r --ignore-remove ibut0


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.
-------------------------------------------------------------------------------
