Commit | Line | Data |
---|---|---|
3e91029a IPG |
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 | 3. 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 | ||
78 | 4. 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 | ||
104 | 5. 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 | ... | |
113 | i2400m_usb 5-4:1.0: firmware interface version 8.0.0 | |
114 | i2400m_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 | ||
122 | 5.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 | ||
132 | options 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 | ||
141 | i2400m.PARAMETER=VALUE | |
142 | ||
143 | 5.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 | ||
149 | 5.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 | ||
165 | 5.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 | ||
203 | 5.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 | |
209 | 45 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 | ||
229 | 5.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 | ||
237 | 5.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 | ||
244 | 5.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 | ||
249 | 6. Troubleshooting | |
250 | ||
251 | 6.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 | ||
256 | i2400m_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. |