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 91. 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 242. Compilation and installation 25 262.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 382.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 623. Installing the firmware 63 64 The firmware can be obtained from http://linuxwimax.org or might have 65 been supplied with your hardware. 66 67 It has to be installed in the target system: 68 * 69$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf 70 71 * NOTE: if your firmware came in an .rpm or .deb file, just install 72 it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg 73 (dpkg -i FIRMWARE.deb) commands. No further action is needed. 74 * BUSTYPE will be usb or sdio, depending on the hardware you have. 75 Each hardware type comes with its own firmware and will not work 76 with other types. 77 784. Design 79 80 This package contains two major parts: a WiMAX kernel stack and a 81 driver for the Intel i2400m. 82 83 The WiMAX stack is designed to provide for common WiMAX control 84 services to current and future WiMAX devices from any vendor; please 85 see README.wimax for details. 86 87 The i2400m kernel driver is broken up in two main parts: the bus 88 generic driver and the bus-specific drivers. The bus generic driver 89 forms the drivercore and contain no knowledge of the actual method we 90 use to connect to the device. The bus specific drivers are just the 91 glue to connect the bus-generic driver and the device. Currently only 92 USB and SDIO are supported. See drivers/net/wimax/i2400m/i2400m.h for 93 more information. 94 95 The bus generic driver is logically broken up in two parts: OS-glue and 96 hardware-glue. The OS-glue interfaces with Linux. The hardware-glue 97 interfaces with the device on using an interface provided by the 98 bus-specific driver. The reason for this breakup is to be able to 99 easily reuse the hardware-glue to write drivers for other OSes; note 100 the hardware glue part is written as a native Linux driver; no 101 abstraction layers are used, so to port to another OS, the Linux kernel 102 API calls should be replaced with the target OS's. 103 1045. Usage 105 106 To load the driver, follow the instructions in the install section; 107 once the driver is loaded, plug in the device (unless it is permanently 108 plugged in). The driver will enumerate the device, upload the firmware 109 and output messages in the kernel log (dmesg, /var/log/messages or 110 /var/log/kern.log) such as: 111 112... 113i2400m_usb 5-4:1.0: firmware interface version 8.0.0 114i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready 115 116 At this point the device is ready to work. 117 118 Current versions require the Intel WiMAX Network Service in userspace 119 to make things work. See the network service's README for instructions 120 on how to scan, connect and disconnect. 121 1225.1. Module parameters 123 124 Module parameters can be set at kernel or module load time or by 125 echoing values: 126 127$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME 128 129 To make changes permanent, for example, for the i2400m module, you can 130 also create a file named /etc/modprobe.d/i2400m containing: 131 132options i2400m idle_mode_disabled=1 133 134 To find which parameters are supported by a module, run: 135 136$ modinfo path/to/module.ko 137 138 During kernel bootup (if the driver is linked in the kernel), specify 139 the following to the kernel command line: 140 141i2400m.PARAMETER=VALUE 142 1435.1.1. i2400m: idle_mode_disabled 144 145 The i2400m module supports a parameter to disable idle mode. This 146 parameter, once set, will take effect only when the device is 147 reinitialized by the driver (eg: following a reset or a reconnect). 148 1495.2. Debug operations: debugfs entries 150 151 The driver will register debugfs entries that allow the user to tweak 152 debug settings. There are three main container directories where 153 entries are placed, which correspond to the three blocks a i2400m WiMAX 154 driver has: 155 * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack 156 controls 157 * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic 158 driver controls 159 * /sys/kernel/debug/wimax:DEVNAME/i2400m-usb (or -sdio) for the 160 bus-specific i2400m-usb or i2400m-sdio controls). 161 162 Of course, if debugfs is mounted in a directory other than 163 /sys/kernel/debug, those paths will change. 164 1655.2.1. Increasing debug output 166 167 The files named *dl_* indicate knobs for controlling the debug output 168 of different submodules: 169 * 170# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* 171/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx 172/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx 173/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif 174/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw 175/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb 176/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx 177/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx 178/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill 179/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev 180/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw 181/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs 182/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver 183/sys/kernel/debug/wimax:wmx0/i2400m/dl_control 184/sys/kernel/debug/wimax:wmx0/wimax_dl_stack 185/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill 186/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset 187/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg 188/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table 189/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs 190 191 By reading the file you can obtain the current value of said debug 192 level; by writing to it, you can set it. 193 194 To increase the debug level of, for example, the i2400m's generic TX 195 engine, just write: 196 197$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx 198 199 Increasing numbers yield increasing debug information; for details of 200 what is printed and the available levels, check the source. The code 201 uses 0 for disabled and increasing values until 8. 202 2035.2.2. RX and TX statistics 204 205 The i2400m/rx_stats and i2400m/tx_stats provide statistics about the 206 data reception/delivery from the device: 207 208$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats 20945 1 3 34 3104 48 480 210 211 The numbers reported are 212 * packets/RX-buffer: total, min, max 213 * RX-buffers: total RX buffers received, accumulated RX buffer size 214 in bytes, min size received, max size received 215 216 Thus, to find the average buffer size received, divide accumulated 217 RX-buffer / total RX-buffers. 218 219 To clear the statistics back to 0, write anything to the rx_stats file: 220 221$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats 222 223 Likewise for TX. 224 225 Note the packets this debug file refers to are not network packet, but 226 packets in the sense of the device-specific protocol for communication 227 to the host. See drivers/net/wimax/i2400m/tx.c. 228 2295.2.3. Tracing messages received from user space 230 231 To echo messages received from user space into the trace pipe that the 232 i2400m driver creates, set the debug file i2400m/trace_msg_from_user to 233 1: 234 * 235$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user 236 2375.2.4. Performing a device reset 238 239 By writing a 0, a 1 or a 2 to the file 240 /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without 241 disconnecting from the bus), cold (disconnecting from the bus) or bus 242 (bus specific) reset on the device. 243 2445.2.5. Asking the device to enter power saving mode 245 246 By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the 247 device will attempt to enter power saving mode. 248 2496. Troubleshooting 250 2516.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed' 252 253 If upon connecting the device, the following is output in the kernel 254 log: 255 256i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2 257 258 This means that the driver cannot locate the firmware file named 259 /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in 260 the right location. 261