
   Driver for the Intel Wireless Wimax Connection 2400m

   (C) 2008 Intel Corporation < linux-wimax@intel.com >

   This provides a driver for the Intel Wireless WiMAX Connection 2400m
   and a basic Linux kernel WiMAX stack.

Requirements

     * Linux installation with Linux kernel 2.6.22 or newer
     * Intel i2400m Echo Peak or Baxter Peak
     * build tools:
          + Linux kernel development package for the target kernel; to
            build against your currently running kernel, you need to have
            the kernel development package corresponding to the running
            image installed (usually if your kernel is named
            linux-VERSION, the development package is called
            linux-dev-VERSION or linux-headers-VERSION).
          + GNU C Compiler, make

Compilation and installation

   To compile

$ cd source/directory
$ make

   Once built you can load and unload using the provided load.sh script;
   load.sh will load the modules, load.sh u will unload them.

   To install in the default kernel directories (and enable auto loading
   when the device is plugged):

$ make install
$ depmod -a

   If your kernel development files are located in a non standard
   directory or if you want to build for a kernel that is not the
   currently running one, set KDIR to the right location:

$ make KDIR=/path/to/kernel/dev/tree

   For more information, please contact linux-wimax@intel.com.

Installing the firmware

   The firmware has been supplied with your hardware and it has to be
   installed in the target system.

$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-1.2.sbcf

     * NOTE: if your firmware came in an .rpm or .deb file, just install
       it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
       (dpkg -i FIRMWARE.deb) commands. No further action is needed.

Usage

   To load the driver, follow the instructions in the install section;
   once the driver is loaded, plug in the device (unless it is permanently
   plugged in). The driver will enumerate the device, upload the firmware
   and output messages in the kernel log (dmesg, /var/log/messages or
   /var/log/kern.log) such as:

...
i2400m_usb 5-4:1.0: firmware interface version 8.0.0
i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready

   At this point the device is ready to work.

   Current versions require the Intel WiMAX Network Service in userspace
   to make things work. This document assumes the service is in place.

    1. Start wimax_appsrv:

$ wimax_appsrv

    2. Switch on the radio:

$ wimaxcu ron
SW Radio is on

    3. Scan for the available base stations and network service providers

$ wimaxcu scan
NSP: Motorola M4
        ID:   111
        RSSI: 50
        CINR: 50
        Network Type: Home network
        Activated

    4. Connect to one of the found base stations

$ wimaxcu connect network 111
NSP Info
        ID:     111
        Name:   Motorola M4
        Realm:
        RSSI:   50
        CINR:   50
        Activated: Yes
        Network Type:   Home network
        Connection Time: 1087604736:111:00

    5. Once this step is done, you can assign an IP address:

$ ifconfig wmx0 100.100.100.10

       and use the connection normally.
       If you want to use DHCP to assign address, currently only the pump
       client is known to work. ISC DHCP does some funny kernel package
       raw management and still won't work with this code.

Controlling the device through sysfs

   sysfs files to control the device behaviour are located in the
   per-device directories /sys/class/net/wmxX*:

$ cd /sys/class/net/wmx0
$ ls -1 wimax/* i2400m*
i2400m_debug_levels
i2400m_debug_stuff
i2400m_reset_cold
i2400m_reset_soft
i2400m_rx_stats
i2400m_tx_stats
i2400m_usb_debug_levels
wimax/debug_levels
wimax/gnl_family_id
wimax/gnl_version

Increasing debug output

   Each *debug_levels file corresponds controls the debug level settings
   for a module (wimax, i2400m or i2400m-usb). Each one contains a list of
   submodules and their current debug levels (default to zero):

$ cat i2400m_debug_levels
0 control
0 driver
0 fw
0 netdev
0 rfkill
0 rx
0 sysfs
0 tx

   To increase the debug level of, for example, the TX engine, just write:

$ echo 3 tx > i2400m_debug_levels

   Increasing numbers yield increasing debug information; for deatails of
   what is printed, check the source.

Performing a device reset

   By writing a 1 to the i2400m_reset_cold file, the device will be
   disconnected from the bus and reenumerated (as if the device had been
   physically plugged in and out.

   By writing a 1 to the i2400m_reset_soft file, the device will
   internally reset, but not reconnect to the bus.

   This feature is currently not working.

RX and TX statistics

   This file provides with statistics about the data reception from the
   device:

$ cat /sys/class/net/wmx0/i2400m_rx_stats
45 1 3
34 3104 48 480

   The numbers reported are
     * packets/RX-buffer: total, min, max
     * RX-buffers: total RX buffers received, accumulated RX buffer size
       in bytes, min size received, max size received

   Thus, to find the average buffer size received, divide accumulated
   RX-buffer / total RX-buffers.

   To clear the statistics back to 0:

$ echo 1 > /sys/class/net/wmx0/i2400m_rx_stats

   Likewise for TX

Troubleshooting

Driver complains about 'i2400m-fw-1.2.sbcf: request failed'

   If upon connecting the device, the following is output in the kernel
   log:

i2400m_usb 5-4:1.0: fw i2400m-fw-1.2.sbcf: request failed: -2

   This means that the driver cannot locate the firmware file named
   /lib/firmware/i2400m-fw-1.2.sbcf. Check that the file is present in the
   right location.

Finding the source code version from compiled modules

   All the modules contain versioning information:

# modinfo drivers/net/wimax/wimax.ko
filename:       drivers/net/wimax/wimax.ko
version:        v1.1.90.5-64c129e112b7+
license:        GPL
...
srcversion:     246E91FEF848C1B502015D8
depends:        rfkill
vermagic:       2.6.24-wusb1 SMP preempt mod_unload CORE2

   So, if you extract the version field (v1.1.90.5-64c129e112b7+), it
   gives us the unique identification of the whole source tree that was
   used to build this driver (64c129e112b7). As well, the + sign says that
   there were local modifications applied to it.

