| |
| 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. |
| |
| 1. Requirements |
| |
| * Linux installation with Linux kernel 2.6.22 or newer (if building |
| from a separate tree) |
| * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel |
| Wireless WiMAX/WiFi Link 5x50 series. |
| * 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 |
| |
| 2. Compilation and installation |
| |
| 2.1. Compilation of the drivers included in the kernel |
| |
| Configure the kernel; to enable the WiMAX drivers select Drivers > |
| Networking Drivers > WiMAX device support. Enable all of them as |
| modules (easier). |
| |
| If USB or SDIO are not enabled in the kernel configuration, the options |
| to build the i2400m USB or SDIO drivers will not show. Enable said |
| subsystems and go back to the WiMAX menu to enable the drivers. |
| |
| Compile and install your kernel as usual. |
| |
| 2.2. Compilation of the drivers distributed as an standalone module |
| |
| 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. |
| |
| 3. Installing the firmware |
| |
| The firmware can be obtained from http://linuxwimax.org or might have |
| been supplied with your hardware. |
| |
| It has to be installed in the target system: |
| * |
| $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.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. |
| * BUSTYPE will be usb or sdio, depending on the hardware you have. |
| Each hardware type comes with its own firmware and will not work |
| with other types. |
| |
| 4. Design |
| |
| This package contains two major parts: a WiMAX kernel stack and a |
| driver for the Intel i2400m. |
| |
| The WiMAX stack is designed to provide for common WiMAX control |
| services to current and future WiMAX devices from any vendor; please |
| see README.wimax for details. |
| |
| The i2400m kernel driver is broken up in two main parts: the bus |
| generic driver and the bus-specific drivers. The bus generic driver |
| forms the drivercore and contain no knowledge of the actual method we |
| use to connect to the device. The bus specific drivers are just the |
| glue to connect the bus-generic driver and the device. Currently only |
| USB and SDIO are supported. See drivers/net/wimax/i2400m/i2400m.h for |
| more information. |
| |
| The bus generic driver is logically broken up in two parts: OS-glue and |
| hardware-glue. The OS-glue interfaces with Linux. The hardware-glue |
| interfaces with the device on using an interface provided by the |
| bus-specific driver. The reason for this breakup is to be able to |
| easily reuse the hardware-glue to write drivers for other OSes; note |
| the hardware glue part is written as a native Linux driver; no |
| abstraction layers are used, so to port to another OS, the Linux kernel |
| API calls should be replaced with the target OS's. |
| |
| 5. 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. See the network service's README for instructions |
| on how to scan, connect and disconnect. |
| |
| 5.1. Module parameters |
| |
| Module parameters can be set at kernel or module load time or by |
| echoing values: |
| |
| $ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME |
| |
| To make changes permanent, for example, for the i2400m module, you can |
| also create a file named /etc/modprobe.d/i2400m containing: |
| |
| options i2400m idle_mode_disabled=1 |
| |
| To find which parameters are supported by a module, run: |
| |
| $ modinfo path/to/module.ko |
| |
| During kernel bootup (if the driver is linked in the kernel), specify |
| the following to the kernel command line: |
| |
| i2400m.PARAMETER=VALUE |
| |
| 5.1.1. i2400m: idle_mode_disabled |
| |
| The i2400m module supports a parameter to disable idle mode. This |
| parameter, once set, will take effect only when the device is |
| reinitialized by the driver (eg: following a reset or a reconnect). |
| |
| 5.2. Debug operations: debugfs entries |
| |
| The driver will register debugfs entries that allow the user to tweak |
| debug settings. There are three main container directories where |
| entries are placed, which correspond to the three blocks a i2400m WiMAX |
| driver has: |
| * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack |
| controls |
| * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic |
| driver controls |
| * /sys/kernel/debug/wimax:DEVNAME/i2400m-usb (or -sdio) for the |
| bus-specific i2400m-usb or i2400m-sdio controls). |
| |
| Of course, if debugfs is mounted in a directory other than |
| /sys/kernel/debug, those paths will change. |
| |
| 5.2.1. Increasing debug output |
| |
| The files named *dl_* indicate knobs for controlling the debug output |
| of different submodules: |
| * |
| # find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\* |
| /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx |
| /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx |
| /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif |
| /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw |
| /sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb |
| /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx |
| /sys/kernel/debug/wimax:wmx0/i2400m/dl_rx |
| /sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill |
| /sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev |
| /sys/kernel/debug/wimax:wmx0/i2400m/dl_fw |
| /sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs |
| /sys/kernel/debug/wimax:wmx0/i2400m/dl_driver |
| /sys/kernel/debug/wimax:wmx0/i2400m/dl_control |
| /sys/kernel/debug/wimax:wmx0/wimax_dl_stack |
| /sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill |
| /sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset |
| /sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg |
| /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table |
| /sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs |
| |
| By reading the file you can obtain the current value of said debug |
| level; by writing to it, you can set it. |
| |
| To increase the debug level of, for example, the i2400m's generic TX |
| engine, just write: |
| |
| $ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx |
| |
| Increasing numbers yield increasing debug information; for details of |
| what is printed and the available levels, check the source. The code |
| uses 0 for disabled and increasing values until 8. |
| |
| 5.2.2. RX and TX statistics |
| |
| The i2400m/rx_stats and i2400m/tx_stats provide statistics about the |
| data reception/delivery from the device: |
| |
| $ cat /sys/kernel/debug/wimax: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, write anything to the rx_stats file: |
| |
| $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats |
| |
| Likewise for TX. |
| |
| Note the packets this debug file refers to are not network packet, but |
| packets in the sense of the device-specific protocol for communication |
| to the host. See drivers/net/wimax/i2400m/tx.c. |
| |
| 5.2.3. Tracing messages received from user space |
| |
| To echo messages received from user space into the trace pipe that the |
| i2400m driver creates, set the debug file i2400m/trace_msg_from_user to |
| 1: |
| * |
| $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user |
| |
| 5.2.4. Performing a device reset |
| |
| By writing a 0, a 1 or a 2 to the file |
| /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without |
| disconnecting from the bus), cold (disconnecting from the bus) or bus |
| (bus specific) reset on the device. |
| |
| 5.2.5. Asking the device to enter power saving mode |
| |
| By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the |
| device will attempt to enter power saving mode. |
| |
| 6. Troubleshooting |
| |
| 6.1. Driver complains about 'i2400m-fw-usb-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-usb-1.3.sbcf: request failed: -2 |
| |
| This means that the driver cannot locate the firmware file named |
| /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in |
| the right location. |