readme.txt

linux下的无线宽带驱动

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