Documentation/admin-guide/wimax/i2400m.rst

   1 .. include:: <isonum.txt>
   2
   3 ====================================================
   4 Driver for the Intel Wireless Wimax Connection 2400m
   5 ====================================================
   6
   7 :Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
   8
   9    This provides a driver for the Intel Wireless WiMAX Connection 2400m
  10    and a basic Linux kernel WiMAX stack.
  11
  12 1. Requirements
  13 ===============
  14
  15      * Linux installation with Linux kernel 2.6.22 or newer (if building
  16        from a separate tree)
  17      * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
  18        Wireless WiMAX/WiFi Link 5x50 series.
  19      * build tools:
  20
  21           + Linux kernel development package for the target kernel; to
  22             build against your currently running kernel, you need to have
  23             the kernel development package corresponding to the running
  24             image installed (usually if your kernel is named
  25             linux-VERSION, the development package is called
  26             linux-dev-VERSION or linux-headers-VERSION).
  27           + GNU C Compiler, make
  28
  29 2. Compilation and installation
  30 ===============================
  31
  32 2.1. Compilation of the drivers included in the kernel
  33 ------------------------------------------------------
  34
  35    Configure the kernel; to enable the WiMAX drivers select Drivers >
  36    Networking Drivers > WiMAX device support. Enable all of them as
  37    modules (easier).
  38
  39    If USB or SDIO are not enabled in the kernel configuration, the options
  40    to build the i2400m USB or SDIO drivers will not show. Enable said
  41    subsystems and go back to the WiMAX menu to enable the drivers.
  42
  43    Compile and install your kernel as usual.
  44
  45 2.2. Compilation of the drivers distributed as an standalone module
  46 -------------------------------------------------------------------
  47
  48    To compile::
  49
  50         $ cd source/directory
  51         $ make
  52
  53    Once built you can load and unload using the provided load.sh script;
  54    load.sh will load the modules, load.sh u will unload them.
  55
  56    To install in the default kernel directories (and enable auto loading
  57    when the device is plugged)::
  58
  59         $ make install
  60         $ depmod -a
  61
  62    If your kernel development files are located in a non standard
  63    directory or if you want to build for a kernel that is not the
  64    currently running one, set KDIR to the right location::
  65
  66         $ make KDIR=/path/to/kernel/dev/tree
  67
  68    For more information, please contact linux-wimax@intel.com.
  69
  70 3. Installing the firmware
  71 --------------------------
  72
  73    The firmware can be obtained from http://linuxwimax.org or might have
  74    been supplied with your hardware.
  75
  76    It has to be installed in the target system::
  77
  78         $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
  79
  80      * NOTE: if your firmware came in an .rpm or .deb file, just install
  81        it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
  82        (dpkg -i FIRMWARE.deb) commands. No further action is needed.
  83      * BUSTYPE will be usb or sdio, depending on the hardware you have.
  84        Each hardware type comes with its own firmware and will not work
  85        with other types.
  86
  87 4. Design
  88 =========
  89
  90    This package contains two major parts: a WiMAX kernel stack and a
  91    driver for the Intel i2400m.
  92
  93    The WiMAX stack is designed to provide for common WiMAX control
  94    services to current and future WiMAX devices from any vendor; please
  95    see README.wimax for details.
  96
  97    The i2400m kernel driver is broken up in two main parts: the bus
  98    generic driver and the bus-specific drivers. The bus generic driver
  99    forms the drivercore and contain no knowledge of the actual method we
 100    use to connect to the device. The bus specific drivers are just the
 101    glue to connect the bus-generic driver and the device. Currently only
 102    USB and SDIO are supported. See drivers/net/wimax/i2400m/i2400m.h for
 103    more information.
 104
 105    The bus generic driver is logically broken up in two parts: OS-glue and
 106    hardware-glue. The OS-glue interfaces with Linux. The hardware-glue
 107    interfaces with the device on using an interface provided by the
 108    bus-specific driver. The reason for this breakup is to be able to
 109    easily reuse the hardware-glue to write drivers for other OSes; note
 110    the hardware glue part is written as a native Linux driver; no
 111    abstraction layers are used, so to port to another OS, the Linux kernel
 112    API calls should be replaced with the target OS's.
 113
 114 5. Usage
 115 ========
 116
 117    To load the driver, follow the instructions in the install section;
 118    once the driver is loaded, plug in the device (unless it is permanently
 119    plugged in). The driver will enumerate the device, upload the firmware
 120    and output messages in the kernel log (dmesg, /var/log/messages or
 121    /var/log/kern.log) such as::
 122
 123         ...
 124         i2400m_usb 5-4:1.0: firmware interface version 8.0.0
 125         i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
 126
 127    At this point the device is ready to work.
 128
 129    Current versions require the Intel WiMAX Network Service in userspace
 130    to make things work. See the network service's README for instructions
 131    on how to scan, connect and disconnect.
 132
 133 5.1. Module parameters
 134 ----------------------
 135
 136    Module parameters can be set at kernel or module load time or by
 137    echoing values::
 138
 139         $ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
 140
 141    To make changes permanent, for example, for the i2400m module, you can
 142    also create a file named /etc/modprobe.d/i2400m containing::
 143
 144         options i2400m idle_mode_disabled=1
 145
 146    To find which parameters are supported by a module, run::
 147
 148         $ modinfo path/to/module.ko
 149
 150    During kernel bootup (if the driver is linked in the kernel), specify
 151    the following to the kernel command line::
 152
 153         i2400m.PARAMETER=VALUE
 154
 155 5.1.1. i2400m: idle_mode_disabled
 156 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 157
 158    The i2400m module supports a parameter to disable idle mode. This
 159    parameter, once set, will take effect only when the device is
 160    reinitialized by the driver (eg: following a reset or a reconnect).
 161
 162 5.2. Debug operations: debugfs entries
 163 --------------------------------------
 164
 165    The driver will register debugfs entries that allow the user to tweak
 166    debug settings. There are three main container directories where
 167    entries are placed, which correspond to the three blocks a i2400m WiMAX
 168    driver has:
 169
 170      * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
 171        controls
 172      * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
 173        driver controls
 174      * /sys/kernel/debug/wimax:DEVNAME/i2400m-usb (or -sdio) for the
 175        bus-specific i2400m-usb or i2400m-sdio controls).
 176
 177    Of course, if debugfs is mounted in a directory other than
 178    /sys/kernel/debug, those paths will change.
 179
 180 5.2.1. Increasing debug output
 181 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 182
 183    The files named *dl_* indicate knobs for controlling the debug output
 184    of different submodules::
 185
 186         # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
 187         /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
 188         /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
 189         /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
 190         /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
 191         /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
 192         /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
 193         /sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
 194         /sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
 195         /sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
 196         /sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
 197         /sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
 198         /sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
 199         /sys/kernel/debug/wimax:wmx0/i2400m/dl_control
 200         /sys/kernel/debug/wimax:wmx0/wimax_dl_stack
 201         /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
 202         /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
 203         /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
 204         /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
 205         /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
 206
 207    By reading the file you can obtain the current value of said debug
 208    level; by writing to it, you can set it.
 209
 210    To increase the debug level of, for example, the i2400m's generic TX
 211    engine, just write::
 212
 213         $ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
 214
 215    Increasing numbers yield increasing debug information; for details of
 216    what is printed and the available levels, check the source. The code
 217    uses 0 for disabled and increasing values until 8.
 218
 219 5.2.2. RX and TX statistics
 220 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 221
 222    The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
 223    data reception/delivery from the device::
 224
 225         $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
 226         45 1 3 34 3104 48 480
 227
 228    The numbers reported are:
 229
 230      * packets/RX-buffer: total, min, max
 231      * RX-buffers: total RX buffers received, accumulated RX buffer size
 232        in bytes, min size received, max size received
 233
 234    Thus, to find the average buffer size received, divide accumulated
 235    RX-buffer / total RX-buffers.
 236
 237    To clear the statistics back to 0, write anything to the rx_stats file::
 238
 239         $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
 240
 241    Likewise for TX.
 242
 243    Note the packets this debug file refers to are not network packet, but
 244    packets in the sense of the device-specific protocol for communication
 245    to the host. See drivers/net/wimax/i2400m/tx.c.
 246
 247 5.2.3. Tracing messages received from user space
 248 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 249
 250    To echo messages received from user space into the trace pipe that the
 251    i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
 252    1::
 253
 254         $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
 255
 256 5.2.4. Performing a device reset
 257 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 258
 259    By writing a 0, a 1 or a 2 to the file
 260    /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
 261    disconnecting from the bus), cold (disconnecting from the bus) or bus
 262    (bus specific) reset on the device.
 263
 264 5.2.5. Asking the device to enter power saving mode
 265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 266
 267    By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
 268    device will attempt to enter power saving mode.
 269
 270 6. Troubleshooting
 271 ==================
 272
 273 6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed``
 274 ----------------------------------------------------------------------
 275
 276    If upon connecting the device, the following is output in the kernel
 277    log::
 278
 279         i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
 280
 281    This means that the driver cannot locate the firmware file named
 282    /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in
 283    the right location.