Documentation/wimax/README.i2400m

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