18c2ecf20Sopenharmony_ci.. include:: <isonum.txt>
28c2ecf20Sopenharmony_ci
38c2ecf20Sopenharmony_ci====================================================
48c2ecf20Sopenharmony_ciDriver for the Intel Wireless Wimax Connection 2400m
58c2ecf20Sopenharmony_ci====================================================
68c2ecf20Sopenharmony_ci
78c2ecf20Sopenharmony_ci:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
88c2ecf20Sopenharmony_ci
98c2ecf20Sopenharmony_ci   This provides a driver for the Intel Wireless WiMAX Connection 2400m
108c2ecf20Sopenharmony_ci   and a basic Linux kernel WiMAX stack.
118c2ecf20Sopenharmony_ci
128c2ecf20Sopenharmony_ci1. Requirements
138c2ecf20Sopenharmony_ci===============
148c2ecf20Sopenharmony_ci
158c2ecf20Sopenharmony_ci     * Linux installation with Linux kernel 2.6.22 or newer (if building
168c2ecf20Sopenharmony_ci       from a separate tree)
178c2ecf20Sopenharmony_ci     * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
188c2ecf20Sopenharmony_ci       Wireless WiMAX/WiFi Link 5x50 series.
198c2ecf20Sopenharmony_ci     * build tools:
208c2ecf20Sopenharmony_ci
218c2ecf20Sopenharmony_ci          + Linux kernel development package for the target kernel; to
228c2ecf20Sopenharmony_ci            build against your currently running kernel, you need to have
238c2ecf20Sopenharmony_ci            the kernel development package corresponding to the running
248c2ecf20Sopenharmony_ci            image installed (usually if your kernel is named
258c2ecf20Sopenharmony_ci            linux-VERSION, the development package is called
268c2ecf20Sopenharmony_ci            linux-dev-VERSION or linux-headers-VERSION).
278c2ecf20Sopenharmony_ci          + GNU C Compiler, make
288c2ecf20Sopenharmony_ci
298c2ecf20Sopenharmony_ci2. Compilation and installation
308c2ecf20Sopenharmony_ci===============================
318c2ecf20Sopenharmony_ci
328c2ecf20Sopenharmony_ci2.1. Compilation of the drivers included in the kernel
338c2ecf20Sopenharmony_ci------------------------------------------------------
348c2ecf20Sopenharmony_ci
358c2ecf20Sopenharmony_ci   Configure the kernel; to enable the WiMAX drivers select Drivers >
368c2ecf20Sopenharmony_ci   Networking Drivers > WiMAX device support. Enable all of them as
378c2ecf20Sopenharmony_ci   modules (easier).
388c2ecf20Sopenharmony_ci
398c2ecf20Sopenharmony_ci   If USB or SDIO are not enabled in the kernel configuration, the options
408c2ecf20Sopenharmony_ci   to build the i2400m USB or SDIO drivers will not show. Enable said
418c2ecf20Sopenharmony_ci   subsystems and go back to the WiMAX menu to enable the drivers.
428c2ecf20Sopenharmony_ci
438c2ecf20Sopenharmony_ci   Compile and install your kernel as usual.
448c2ecf20Sopenharmony_ci
458c2ecf20Sopenharmony_ci2.2. Compilation of the drivers distributed as an standalone module
468c2ecf20Sopenharmony_ci-------------------------------------------------------------------
478c2ecf20Sopenharmony_ci
488c2ecf20Sopenharmony_ci   To compile::
498c2ecf20Sopenharmony_ci
508c2ecf20Sopenharmony_ci	$ cd source/directory
518c2ecf20Sopenharmony_ci	$ make
528c2ecf20Sopenharmony_ci
538c2ecf20Sopenharmony_ci   Once built you can load and unload using the provided load.sh script;
548c2ecf20Sopenharmony_ci   load.sh will load the modules, load.sh u will unload them.
558c2ecf20Sopenharmony_ci
568c2ecf20Sopenharmony_ci   To install in the default kernel directories (and enable auto loading
578c2ecf20Sopenharmony_ci   when the device is plugged)::
588c2ecf20Sopenharmony_ci
598c2ecf20Sopenharmony_ci	$ make install
608c2ecf20Sopenharmony_ci	$ depmod -a
618c2ecf20Sopenharmony_ci
628c2ecf20Sopenharmony_ci   If your kernel development files are located in a non standard
638c2ecf20Sopenharmony_ci   directory or if you want to build for a kernel that is not the
648c2ecf20Sopenharmony_ci   currently running one, set KDIR to the right location::
658c2ecf20Sopenharmony_ci
668c2ecf20Sopenharmony_ci	$ make KDIR=/path/to/kernel/dev/tree
678c2ecf20Sopenharmony_ci
688c2ecf20Sopenharmony_ci   For more information, please contact linux-wimax@intel.com.
698c2ecf20Sopenharmony_ci
708c2ecf20Sopenharmony_ci3. Installing the firmware
718c2ecf20Sopenharmony_ci--------------------------
728c2ecf20Sopenharmony_ci
738c2ecf20Sopenharmony_ci   The firmware can be obtained from http://linuxwimax.org or might have
748c2ecf20Sopenharmony_ci   been supplied with your hardware.
758c2ecf20Sopenharmony_ci
768c2ecf20Sopenharmony_ci   It has to be installed in the target system::
778c2ecf20Sopenharmony_ci
788c2ecf20Sopenharmony_ci	$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
798c2ecf20Sopenharmony_ci
808c2ecf20Sopenharmony_ci     * NOTE: if your firmware came in an .rpm or .deb file, just install
818c2ecf20Sopenharmony_ci       it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
828c2ecf20Sopenharmony_ci       (dpkg -i FIRMWARE.deb) commands. No further action is needed.
838c2ecf20Sopenharmony_ci     * BUSTYPE will be usb or sdio, depending on the hardware you have.
848c2ecf20Sopenharmony_ci       Each hardware type comes with its own firmware and will not work
858c2ecf20Sopenharmony_ci       with other types.
868c2ecf20Sopenharmony_ci
878c2ecf20Sopenharmony_ci4. Design
888c2ecf20Sopenharmony_ci=========
898c2ecf20Sopenharmony_ci
908c2ecf20Sopenharmony_ci   This package contains two major parts: a WiMAX kernel stack and a
918c2ecf20Sopenharmony_ci   driver for the Intel i2400m.
928c2ecf20Sopenharmony_ci
938c2ecf20Sopenharmony_ci   The WiMAX stack is designed to provide for common WiMAX control
948c2ecf20Sopenharmony_ci   services to current and future WiMAX devices from any vendor; please
958c2ecf20Sopenharmony_ci   see README.wimax for details.
968c2ecf20Sopenharmony_ci
978c2ecf20Sopenharmony_ci   The i2400m kernel driver is broken up in two main parts: the bus
988c2ecf20Sopenharmony_ci   generic driver and the bus-specific drivers. The bus generic driver
998c2ecf20Sopenharmony_ci   forms the drivercore and contain no knowledge of the actual method we
1008c2ecf20Sopenharmony_ci   use to connect to the device. The bus specific drivers are just the
1018c2ecf20Sopenharmony_ci   glue to connect the bus-generic driver and the device. Currently only
1028c2ecf20Sopenharmony_ci   USB and SDIO are supported. See drivers/net/wimax/i2400m/i2400m.h for
1038c2ecf20Sopenharmony_ci   more information.
1048c2ecf20Sopenharmony_ci
1058c2ecf20Sopenharmony_ci   The bus generic driver is logically broken up in two parts: OS-glue and
1068c2ecf20Sopenharmony_ci   hardware-glue. The OS-glue interfaces with Linux. The hardware-glue
1078c2ecf20Sopenharmony_ci   interfaces with the device on using an interface provided by the
1088c2ecf20Sopenharmony_ci   bus-specific driver. The reason for this breakup is to be able to
1098c2ecf20Sopenharmony_ci   easily reuse the hardware-glue to write drivers for other OSes; note
1108c2ecf20Sopenharmony_ci   the hardware glue part is written as a native Linux driver; no
1118c2ecf20Sopenharmony_ci   abstraction layers are used, so to port to another OS, the Linux kernel
1128c2ecf20Sopenharmony_ci   API calls should be replaced with the target OS's.
1138c2ecf20Sopenharmony_ci
1148c2ecf20Sopenharmony_ci5. Usage
1158c2ecf20Sopenharmony_ci========
1168c2ecf20Sopenharmony_ci
1178c2ecf20Sopenharmony_ci   To load the driver, follow the instructions in the install section;
1188c2ecf20Sopenharmony_ci   once the driver is loaded, plug in the device (unless it is permanently
1198c2ecf20Sopenharmony_ci   plugged in). The driver will enumerate the device, upload the firmware
1208c2ecf20Sopenharmony_ci   and output messages in the kernel log (dmesg, /var/log/messages or
1218c2ecf20Sopenharmony_ci   /var/log/kern.log) such as::
1228c2ecf20Sopenharmony_ci
1238c2ecf20Sopenharmony_ci	...
1248c2ecf20Sopenharmony_ci	i2400m_usb 5-4:1.0: firmware interface version 8.0.0
1258c2ecf20Sopenharmony_ci	i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
1268c2ecf20Sopenharmony_ci
1278c2ecf20Sopenharmony_ci   At this point the device is ready to work.
1288c2ecf20Sopenharmony_ci
1298c2ecf20Sopenharmony_ci   Current versions require the Intel WiMAX Network Service in userspace
1308c2ecf20Sopenharmony_ci   to make things work. See the network service's README for instructions
1318c2ecf20Sopenharmony_ci   on how to scan, connect and disconnect.
1328c2ecf20Sopenharmony_ci
1338c2ecf20Sopenharmony_ci5.1. Module parameters
1348c2ecf20Sopenharmony_ci----------------------
1358c2ecf20Sopenharmony_ci
1368c2ecf20Sopenharmony_ci   Module parameters can be set at kernel or module load time or by
1378c2ecf20Sopenharmony_ci   echoing values::
1388c2ecf20Sopenharmony_ci
1398c2ecf20Sopenharmony_ci	$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
1408c2ecf20Sopenharmony_ci
1418c2ecf20Sopenharmony_ci   To make changes permanent, for example, for the i2400m module, you can
1428c2ecf20Sopenharmony_ci   also create a file named /etc/modprobe.d/i2400m containing::
1438c2ecf20Sopenharmony_ci
1448c2ecf20Sopenharmony_ci	options i2400m idle_mode_disabled=1
1458c2ecf20Sopenharmony_ci
1468c2ecf20Sopenharmony_ci   To find which parameters are supported by a module, run::
1478c2ecf20Sopenharmony_ci
1488c2ecf20Sopenharmony_ci	$ modinfo path/to/module.ko
1498c2ecf20Sopenharmony_ci
1508c2ecf20Sopenharmony_ci   During kernel bootup (if the driver is linked in the kernel), specify
1518c2ecf20Sopenharmony_ci   the following to the kernel command line::
1528c2ecf20Sopenharmony_ci
1538c2ecf20Sopenharmony_ci	i2400m.PARAMETER=VALUE
1548c2ecf20Sopenharmony_ci
1558c2ecf20Sopenharmony_ci5.1.1. i2400m: idle_mode_disabled
1568c2ecf20Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1578c2ecf20Sopenharmony_ci
1588c2ecf20Sopenharmony_ci   The i2400m module supports a parameter to disable idle mode. This
1598c2ecf20Sopenharmony_ci   parameter, once set, will take effect only when the device is
1608c2ecf20Sopenharmony_ci   reinitialized by the driver (eg: following a reset or a reconnect).
1618c2ecf20Sopenharmony_ci
1628c2ecf20Sopenharmony_ci5.2. Debug operations: debugfs entries
1638c2ecf20Sopenharmony_ci--------------------------------------
1648c2ecf20Sopenharmony_ci
1658c2ecf20Sopenharmony_ci   The driver will register debugfs entries that allow the user to tweak
1668c2ecf20Sopenharmony_ci   debug settings. There are three main container directories where
1678c2ecf20Sopenharmony_ci   entries are placed, which correspond to the three blocks a i2400m WiMAX
1688c2ecf20Sopenharmony_ci   driver has:
1698c2ecf20Sopenharmony_ci
1708c2ecf20Sopenharmony_ci     * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
1718c2ecf20Sopenharmony_ci       controls
1728c2ecf20Sopenharmony_ci     * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
1738c2ecf20Sopenharmony_ci       driver controls
1748c2ecf20Sopenharmony_ci     * /sys/kernel/debug/wimax:DEVNAME/i2400m-usb (or -sdio) for the
1758c2ecf20Sopenharmony_ci       bus-specific i2400m-usb or i2400m-sdio controls).
1768c2ecf20Sopenharmony_ci
1778c2ecf20Sopenharmony_ci   Of course, if debugfs is mounted in a directory other than
1788c2ecf20Sopenharmony_ci   /sys/kernel/debug, those paths will change.
1798c2ecf20Sopenharmony_ci
1808c2ecf20Sopenharmony_ci5.2.1. Increasing debug output
1818c2ecf20Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1828c2ecf20Sopenharmony_ci
1838c2ecf20Sopenharmony_ci   The files named *dl_* indicate knobs for controlling the debug output
1848c2ecf20Sopenharmony_ci   of different submodules::
1858c2ecf20Sopenharmony_ci
1868c2ecf20Sopenharmony_ci	# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
1878c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
1888c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
1898c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
1908c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
1918c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
1928c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
1938c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
1948c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
1958c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
1968c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
1978c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
1988c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
1998c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
2008c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
2018c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
2028c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
2038c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
2048c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
2058c2ecf20Sopenharmony_ci	/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
2068c2ecf20Sopenharmony_ci
2078c2ecf20Sopenharmony_ci   By reading the file you can obtain the current value of said debug
2088c2ecf20Sopenharmony_ci   level; by writing to it, you can set it.
2098c2ecf20Sopenharmony_ci
2108c2ecf20Sopenharmony_ci   To increase the debug level of, for example, the i2400m's generic TX
2118c2ecf20Sopenharmony_ci   engine, just write::
2128c2ecf20Sopenharmony_ci
2138c2ecf20Sopenharmony_ci	$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
2148c2ecf20Sopenharmony_ci
2158c2ecf20Sopenharmony_ci   Increasing numbers yield increasing debug information; for details of
2168c2ecf20Sopenharmony_ci   what is printed and the available levels, check the source. The code
2178c2ecf20Sopenharmony_ci   uses 0 for disabled and increasing values until 8.
2188c2ecf20Sopenharmony_ci
2198c2ecf20Sopenharmony_ci5.2.2. RX and TX statistics
2208c2ecf20Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^^
2218c2ecf20Sopenharmony_ci
2228c2ecf20Sopenharmony_ci   The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
2238c2ecf20Sopenharmony_ci   data reception/delivery from the device::
2248c2ecf20Sopenharmony_ci
2258c2ecf20Sopenharmony_ci	$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
2268c2ecf20Sopenharmony_ci	45 1 3 34 3104 48 480
2278c2ecf20Sopenharmony_ci
2288c2ecf20Sopenharmony_ci   The numbers reported are:
2298c2ecf20Sopenharmony_ci
2308c2ecf20Sopenharmony_ci     * packets/RX-buffer: total, min, max
2318c2ecf20Sopenharmony_ci     * RX-buffers: total RX buffers received, accumulated RX buffer size
2328c2ecf20Sopenharmony_ci       in bytes, min size received, max size received
2338c2ecf20Sopenharmony_ci
2348c2ecf20Sopenharmony_ci   Thus, to find the average buffer size received, divide accumulated
2358c2ecf20Sopenharmony_ci   RX-buffer / total RX-buffers.
2368c2ecf20Sopenharmony_ci
2378c2ecf20Sopenharmony_ci   To clear the statistics back to 0, write anything to the rx_stats file::
2388c2ecf20Sopenharmony_ci
2398c2ecf20Sopenharmony_ci	$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
2408c2ecf20Sopenharmony_ci
2418c2ecf20Sopenharmony_ci   Likewise for TX.
2428c2ecf20Sopenharmony_ci
2438c2ecf20Sopenharmony_ci   Note the packets this debug file refers to are not network packet, but
2448c2ecf20Sopenharmony_ci   packets in the sense of the device-specific protocol for communication
2458c2ecf20Sopenharmony_ci   to the host. See drivers/net/wimax/i2400m/tx.c.
2468c2ecf20Sopenharmony_ci
2478c2ecf20Sopenharmony_ci5.2.3. Tracing messages received from user space
2488c2ecf20Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2498c2ecf20Sopenharmony_ci
2508c2ecf20Sopenharmony_ci   To echo messages received from user space into the trace pipe that the
2518c2ecf20Sopenharmony_ci   i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
2528c2ecf20Sopenharmony_ci   1::
2538c2ecf20Sopenharmony_ci
2548c2ecf20Sopenharmony_ci	$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
2558c2ecf20Sopenharmony_ci
2568c2ecf20Sopenharmony_ci5.2.4. Performing a device reset
2578c2ecf20Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2588c2ecf20Sopenharmony_ci
2598c2ecf20Sopenharmony_ci   By writing a 0, a 1 or a 2 to the file
2608c2ecf20Sopenharmony_ci   /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
2618c2ecf20Sopenharmony_ci   disconnecting from the bus), cold (disconnecting from the bus) or bus
2628c2ecf20Sopenharmony_ci   (bus specific) reset on the device.
2638c2ecf20Sopenharmony_ci
2648c2ecf20Sopenharmony_ci5.2.5. Asking the device to enter power saving mode
2658c2ecf20Sopenharmony_ci^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2668c2ecf20Sopenharmony_ci
2678c2ecf20Sopenharmony_ci   By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
2688c2ecf20Sopenharmony_ci   device will attempt to enter power saving mode.
2698c2ecf20Sopenharmony_ci
2708c2ecf20Sopenharmony_ci6. Troubleshooting
2718c2ecf20Sopenharmony_ci==================
2728c2ecf20Sopenharmony_ci
2738c2ecf20Sopenharmony_ci6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed``
2748c2ecf20Sopenharmony_ci----------------------------------------------------------------------
2758c2ecf20Sopenharmony_ci
2768c2ecf20Sopenharmony_ci   If upon connecting the device, the following is output in the kernel
2778c2ecf20Sopenharmony_ci   log::
2788c2ecf20Sopenharmony_ci
2798c2ecf20Sopenharmony_ci	i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
2808c2ecf20Sopenharmony_ci
2818c2ecf20Sopenharmony_ci   This means that the driver cannot locate the firmware file named
2828c2ecf20Sopenharmony_ci   /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in
2838c2ecf20Sopenharmony_ci   the right location.
284