1.. include:: <isonum.txt>
2
3====================================================
4Driver 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
121. 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
292. Compilation and installation
30===============================
31
322.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
452.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
703. 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
874. 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
1145. 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
1335.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
1555.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
1625.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
1805.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
2195.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
2475.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
2565.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
2645.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
2706. Troubleshooting
271==================
272
2736.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.
284