Commit | Line | Data |
---|---|---|
5c58edc6 EG |
1 | /****************************************************************************** |
2 | * | |
3 | * This file is provided under a dual BSD/GPLv2 license. When using or | |
4 | * redistributing this file, you may do so under either license. | |
5 | * | |
6 | * GPL LICENSE SUMMARY | |
7 | * | |
51368bf7 | 8 | * Copyright(c) 2007 - 2014 Intel Corporation. All rights reserved. |
5c58edc6 EG |
9 | * |
10 | * This program is free software; you can redistribute it and/or modify | |
11 | * it under the terms of version 2 of the GNU General Public License as | |
12 | * published by the Free Software Foundation. | |
13 | * | |
14 | * This program is distributed in the hope that it will be useful, but | |
15 | * WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
17 | * General Public License for more details. | |
18 | * | |
19 | * You should have received a copy of the GNU General Public License | |
20 | * along with this program; if not, write to the Free Software | |
21 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110, | |
22 | * USA | |
23 | * | |
24 | * The full GNU General Public License is included in this distribution | |
410dc5aa | 25 | * in the file called COPYING. |
5c58edc6 EG |
26 | * |
27 | * Contact Information: | |
28 | * Intel Linux Wireless <ilw@linux.intel.com> | |
29 | * Intel Corporation, 5200 N.E. Elam Young Parkway, Hillsboro, OR 97124-6497 | |
30 | * | |
31 | * BSD LICENSE | |
32 | * | |
51368bf7 | 33 | * Copyright(c) 2005 - 2014 Intel Corporation. All rights reserved. |
5c58edc6 EG |
34 | * All rights reserved. |
35 | * | |
36 | * Redistribution and use in source and binary forms, with or without | |
37 | * modification, are permitted provided that the following conditions | |
38 | * are met: | |
39 | * | |
40 | * * Redistributions of source code must retain the above copyright | |
41 | * notice, this list of conditions and the following disclaimer. | |
42 | * * Redistributions in binary form must reproduce the above copyright | |
43 | * notice, this list of conditions and the following disclaimer in | |
44 | * the documentation and/or other materials provided with the | |
45 | * distribution. | |
46 | * * Neither the name Intel Corporation nor the names of its | |
47 | * contributors may be used to endorse or promote products derived | |
48 | * from this software without specific prior written permission. | |
49 | * | |
50 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
51 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
52 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
53 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
54 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
55 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
56 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
57 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
58 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
59 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
60 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
61 | * | |
62 | *****************************************************************************/ | |
63 | #include <linux/completion.h> | |
15854ef9 JB |
64 | #include <linux/dma-mapping.h> |
65 | #include <linux/firmware.h> | |
66 | #include <linux/module.h> | |
83f84d7b | 67 | #include <linux/vmalloc.h> |
5c58edc6 EG |
68 | |
69 | #include "iwl-drv.h" | |
c15797e6 | 70 | #include "iwl-debug.h" |
5c58edc6 | 71 | #include "iwl-trans.h" |
d0f76d68 | 72 | #include "iwl-op-mode.h" |
0cedacc5 | 73 | #include "iwl-agn-hw.h" |
6238b008 JB |
74 | #include "iwl-fw.h" |
75 | #include "iwl-config.h" | |
65de7e84 | 76 | #include "iwl-modparams.h" |
5c58edc6 | 77 | |
0692fe41 | 78 | /* private includes */ |
3995deaf | 79 | #include "iwl-fw-file.h" |
0692fe41 | 80 | |
cc5f7e39 DF |
81 | /****************************************************************************** |
82 | * | |
83 | * module boiler plate | |
84 | * | |
85 | ******************************************************************************/ | |
86 | ||
87 | /* | |
88 | * module name, copyright, version, etc. | |
89 | */ | |
90 | #define DRV_DESCRIPTION "Intel(R) Wireless WiFi driver for Linux" | |
91 | ||
92 | #ifdef CONFIG_IWLWIFI_DEBUG | |
93 | #define VD "d" | |
94 | #else | |
95 | #define VD | |
96 | #endif | |
97 | ||
98 | #define DRV_VERSION IWLWIFI_VERSION VD | |
99 | ||
100 | MODULE_DESCRIPTION(DRV_DESCRIPTION); | |
101 | MODULE_VERSION(DRV_VERSION); | |
102 | MODULE_AUTHOR(DRV_COPYRIGHT " " DRV_AUTHOR); | |
103 | MODULE_LICENSE("GPL"); | |
104 | ||
9da987ac MV |
105 | #ifdef CONFIG_IWLWIFI_DEBUGFS |
106 | static struct dentry *iwl_dbgfs_root; | |
107 | #endif | |
108 | ||
965974a6 JB |
109 | /** |
110 | * struct iwl_drv - drv common data | |
cc5f7e39 | 111 | * @list: list of drv structures using this opmode |
965974a6 | 112 | * @fw: the iwl_fw structure |
965974a6 | 113 | * @op_mode: the running op_mode |
68f360dc | 114 | * @trans: transport layer |
4b9844f5 | 115 | * @dev: for debug prints only |
68f360dc | 116 | * @cfg: configuration struct |
965974a6 JB |
117 | * @fw_index: firmware revision to try loading |
118 | * @firmware_name: composite filename of ucode file to load | |
119 | * @request_firmware_complete: the firmware has been obtained from user space | |
120 | */ | |
121 | struct iwl_drv { | |
cc5f7e39 | 122 | struct list_head list; |
965974a6 JB |
123 | struct iwl_fw fw; |
124 | ||
965974a6 | 125 | struct iwl_op_mode *op_mode; |
9130bab1 | 126 | struct iwl_trans *trans; |
4b9844f5 | 127 | struct device *dev; |
68f360dc | 128 | const struct iwl_cfg *cfg; |
965974a6 JB |
129 | |
130 | int fw_index; /* firmware we're trying to load */ | |
131 | char firmware_name[25]; /* name of firmware file to load */ | |
132 | ||
133 | struct completion request_firmware_complete; | |
9da987ac MV |
134 | |
135 | #ifdef CONFIG_IWLWIFI_DEBUGFS | |
136 | struct dentry *dbgfs_drv; | |
137 | struct dentry *dbgfs_trans; | |
138 | struct dentry *dbgfs_op_mode; | |
139 | #endif | |
965974a6 JB |
140 | }; |
141 | ||
8ca151b5 JB |
142 | enum { |
143 | DVM_OP_MODE = 0, | |
144 | MVM_OP_MODE = 1, | |
145 | }; | |
965974a6 | 146 | |
ff1ffb85 JB |
147 | /* Protects the table contents, i.e. the ops pointer & drv list */ |
148 | static struct mutex iwlwifi_opmode_table_mtx; | |
cc5f7e39 DF |
149 | static struct iwlwifi_opmode_table { |
150 | const char *name; /* name: iwldvm, iwlmvm, etc */ | |
151 | const struct iwl_op_mode_ops *ops; /* pointer to op_mode ops */ | |
152 | struct list_head drv; /* list of devices using this op_mode */ | |
153 | } iwlwifi_opmode_table[] = { /* ops set when driver is initialized */ | |
8ca151b5 JB |
154 | [DVM_OP_MODE] = { .name = "iwldvm", .ops = NULL }, |
155 | [MVM_OP_MODE] = { .name = "iwlmvm", .ops = NULL }, | |
cc5f7e39 | 156 | }; |
965974a6 | 157 | |
0cedacc5 DS |
158 | /* |
159 | * struct fw_sec: Just for the image parsing proccess. | |
160 | * For the fw storage we are using struct fw_desc. | |
161 | */ | |
162 | struct fw_sec { | |
163 | const void *data; /* the sec data */ | |
164 | size_t size; /* section size */ | |
165 | u32 offset; /* offset of writing in the device */ | |
166 | }; | |
167 | ||
965974a6 | 168 | static void iwl_free_fw_desc(struct iwl_drv *drv, struct fw_desc *desc) |
15854ef9 | 169 | { |
83f84d7b JB |
170 | vfree(desc->data); |
171 | desc->data = NULL; | |
15854ef9 JB |
172 | desc->len = 0; |
173 | } | |
174 | ||
965974a6 | 175 | static void iwl_free_fw_img(struct iwl_drv *drv, struct fw_img *img) |
15854ef9 | 176 | { |
6dfa8d01 DS |
177 | int i; |
178 | for (i = 0; i < IWL_UCODE_SECTION_MAX; i++) | |
179 | iwl_free_fw_desc(drv, &img->sec[i]); | |
15854ef9 JB |
180 | } |
181 | ||
965974a6 | 182 | static void iwl_dealloc_ucode(struct iwl_drv *drv) |
15854ef9 | 183 | { |
6dfa8d01 DS |
184 | int i; |
185 | for (i = 0; i < IWL_UCODE_TYPE_MAX; i++) | |
186 | iwl_free_fw_img(drv, drv->fw.img + i); | |
15854ef9 JB |
187 | } |
188 | ||
965974a6 | 189 | static int iwl_alloc_fw_desc(struct iwl_drv *drv, struct fw_desc *desc, |
83f84d7b | 190 | struct fw_sec *sec) |
15854ef9 | 191 | { |
83f84d7b JB |
192 | void *data; |
193 | ||
194 | desc->data = NULL; | |
195 | ||
196 | if (!sec || !sec->size) | |
15854ef9 | 197 | return -EINVAL; |
15854ef9 | 198 | |
83f84d7b JB |
199 | data = vmalloc(sec->size); |
200 | if (!data) | |
15854ef9 JB |
201 | return -ENOMEM; |
202 | ||
0cedacc5 DS |
203 | desc->len = sec->size; |
204 | desc->offset = sec->offset; | |
83f84d7b JB |
205 | memcpy(data, sec->data, desc->len); |
206 | desc->data = data; | |
207 | ||
15854ef9 JB |
208 | return 0; |
209 | } | |
210 | ||
1c8e11e1 EG |
211 | static void iwl_req_fw_callback(const struct firmware *ucode_raw, |
212 | void *context); | |
15854ef9 JB |
213 | |
214 | #define UCODE_EXPERIMENTAL_INDEX 100 | |
215 | #define UCODE_EXPERIMENTAL_TAG "exp" | |
216 | ||
965974a6 | 217 | static int iwl_request_firmware(struct iwl_drv *drv, bool first) |
15854ef9 | 218 | { |
68f360dc | 219 | const char *name_pre = drv->cfg->fw_name_pre; |
15854ef9 JB |
220 | char tag[8]; |
221 | ||
222 | if (first) { | |
223 | #ifdef CONFIG_IWLWIFI_DEBUG_EXPERIMENTAL_UCODE | |
965974a6 | 224 | drv->fw_index = UCODE_EXPERIMENTAL_INDEX; |
15854ef9 | 225 | strcpy(tag, UCODE_EXPERIMENTAL_TAG); |
965974a6 | 226 | } else if (drv->fw_index == UCODE_EXPERIMENTAL_INDEX) { |
15854ef9 | 227 | #endif |
68f360dc | 228 | drv->fw_index = drv->cfg->ucode_api_max; |
965974a6 | 229 | sprintf(tag, "%d", drv->fw_index); |
15854ef9 | 230 | } else { |
965974a6 JB |
231 | drv->fw_index--; |
232 | sprintf(tag, "%d", drv->fw_index); | |
15854ef9 JB |
233 | } |
234 | ||
68f360dc | 235 | if (drv->fw_index < drv->cfg->ucode_api_min) { |
965974a6 | 236 | IWL_ERR(drv, "no suitable firmware found!\n"); |
15854ef9 JB |
237 | return -ENOENT; |
238 | } | |
239 | ||
965974a6 | 240 | sprintf(drv->firmware_name, "%s%s%s", name_pre, tag, ".ucode"); |
15854ef9 | 241 | |
965974a6 JB |
242 | IWL_DEBUG_INFO(drv, "attempting to load firmware %s'%s'\n", |
243 | (drv->fw_index == UCODE_EXPERIMENTAL_INDEX) | |
15854ef9 | 244 | ? "EXPERIMENTAL " : "", |
965974a6 | 245 | drv->firmware_name); |
15854ef9 | 246 | |
965974a6 | 247 | return request_firmware_nowait(THIS_MODULE, 1, drv->firmware_name, |
93faaeea | 248 | drv->trans->dev, |
1c8e11e1 | 249 | GFP_KERNEL, drv, iwl_req_fw_callback); |
15854ef9 JB |
250 | } |
251 | ||
0cedacc5 | 252 | struct fw_img_parsing { |
6dfa8d01 | 253 | struct fw_sec sec[IWL_UCODE_SECTION_MAX]; |
0cedacc5 DS |
254 | int sec_counter; |
255 | }; | |
256 | ||
ed8c8365 DS |
257 | /* |
258 | * struct fw_sec_parsing: to extract fw section and it's offset from tlv | |
259 | */ | |
260 | struct fw_sec_parsing { | |
261 | __le32 offset; | |
262 | const u8 data[]; | |
263 | } __packed; | |
264 | ||
265 | /** | |
266 | * struct iwl_tlv_calib_data - parse the default calib data from TLV | |
267 | * | |
268 | * @ucode_type: the uCode to which the following default calib relates. | |
269 | * @calib: default calibrations. | |
270 | */ | |
271 | struct iwl_tlv_calib_data { | |
272 | __le32 ucode_type; | |
aa2b1770 | 273 | struct iwl_tlv_calib_ctrl calib; |
ed8c8365 DS |
274 | } __packed; |
275 | ||
0cedacc5 DS |
276 | struct iwl_firmware_pieces { |
277 | struct fw_img_parsing img[IWL_UCODE_TYPE_MAX]; | |
15854ef9 JB |
278 | |
279 | u32 init_evtlog_ptr, init_evtlog_size, init_errlog_ptr; | |
280 | u32 inst_evtlog_ptr, inst_evtlog_size, inst_errlog_ptr; | |
281 | }; | |
282 | ||
0cedacc5 DS |
283 | /* |
284 | * These functions are just to extract uCode section data from the pieces | |
285 | * structure. | |
286 | */ | |
287 | static struct fw_sec *get_sec(struct iwl_firmware_pieces *pieces, | |
288 | enum iwl_ucode_type type, | |
289 | int sec) | |
290 | { | |
291 | return &pieces->img[type].sec[sec]; | |
292 | } | |
293 | ||
294 | static void set_sec_data(struct iwl_firmware_pieces *pieces, | |
295 | enum iwl_ucode_type type, | |
296 | int sec, | |
297 | const void *data) | |
298 | { | |
299 | pieces->img[type].sec[sec].data = data; | |
300 | } | |
301 | ||
302 | static void set_sec_size(struct iwl_firmware_pieces *pieces, | |
303 | enum iwl_ucode_type type, | |
304 | int sec, | |
305 | size_t size) | |
306 | { | |
307 | pieces->img[type].sec[sec].size = size; | |
308 | } | |
309 | ||
310 | static size_t get_sec_size(struct iwl_firmware_pieces *pieces, | |
311 | enum iwl_ucode_type type, | |
312 | int sec) | |
313 | { | |
314 | return pieces->img[type].sec[sec].size; | |
315 | } | |
316 | ||
317 | static void set_sec_offset(struct iwl_firmware_pieces *pieces, | |
318 | enum iwl_ucode_type type, | |
319 | int sec, | |
320 | u32 offset) | |
321 | { | |
322 | pieces->img[type].sec[sec].offset = offset; | |
323 | } | |
324 | ||
e36e5433 MS |
325 | static int iwl_store_cscheme(struct iwl_fw *fw, const u8 *data, const u32 len) |
326 | { | |
327 | int i, j; | |
328 | struct iwl_fw_cscheme_list *l = (struct iwl_fw_cscheme_list *)data; | |
329 | struct iwl_fw_cipher_scheme *fwcs; | |
330 | struct ieee80211_cipher_scheme *cs; | |
331 | u32 cipher; | |
332 | ||
333 | if (len < sizeof(*l) || | |
334 | len < sizeof(l->size) + l->size * sizeof(l->cs[0])) | |
335 | return -EINVAL; | |
336 | ||
337 | for (i = 0, j = 0; i < IWL_UCODE_MAX_CS && i < l->size; i++) { | |
338 | fwcs = &l->cs[j]; | |
339 | cipher = le32_to_cpu(fwcs->cipher); | |
340 | ||
341 | /* we skip schemes with zero cipher suite selector */ | |
342 | if (!cipher) | |
343 | continue; | |
344 | ||
345 | cs = &fw->cs[j++]; | |
346 | cs->cipher = cipher; | |
347 | cs->iftype = BIT(NL80211_IFTYPE_STATION); | |
348 | cs->hdr_len = fwcs->hdr_len; | |
349 | cs->pn_len = fwcs->pn_len; | |
350 | cs->pn_off = fwcs->pn_off; | |
351 | cs->key_idx_off = fwcs->key_idx_off; | |
352 | cs->key_idx_mask = fwcs->key_idx_mask; | |
353 | cs->key_idx_shift = fwcs->key_idx_shift; | |
354 | cs->mic_len = fwcs->mic_len; | |
355 | } | |
356 | ||
357 | return 0; | |
358 | } | |
359 | ||
ed8c8365 DS |
360 | /* |
361 | * Gets uCode section from tlv. | |
362 | */ | |
363 | static int iwl_store_ucode_sec(struct iwl_firmware_pieces *pieces, | |
364 | const void *data, enum iwl_ucode_type type, | |
365 | int size) | |
366 | { | |
367 | struct fw_img_parsing *img; | |
368 | struct fw_sec *sec; | |
369 | struct fw_sec_parsing *sec_parse; | |
370 | ||
371 | if (WARN_ON(!pieces || !data || type >= IWL_UCODE_TYPE_MAX)) | |
372 | return -1; | |
373 | ||
374 | sec_parse = (struct fw_sec_parsing *)data; | |
375 | ||
376 | img = &pieces->img[type]; | |
377 | sec = &img->sec[img->sec_counter]; | |
378 | ||
379 | sec->offset = le32_to_cpu(sec_parse->offset); | |
380 | sec->data = sec_parse->data; | |
1176f431 | 381 | sec->size = size - sizeof(sec_parse->offset); |
ed8c8365 DS |
382 | |
383 | ++img->sec_counter; | |
384 | ||
385 | return 0; | |
386 | } | |
387 | ||
388 | static int iwl_set_default_calib(struct iwl_drv *drv, const u8 *data) | |
389 | { | |
390 | struct iwl_tlv_calib_data *def_calib = | |
391 | (struct iwl_tlv_calib_data *)data; | |
392 | u32 ucode_type = le32_to_cpu(def_calib->ucode_type); | |
393 | if (ucode_type >= IWL_UCODE_TYPE_MAX) { | |
394 | IWL_ERR(drv, "Wrong ucode_type %u for default calibration.\n", | |
395 | ucode_type); | |
396 | return -EINVAL; | |
397 | } | |
aa2b1770 JB |
398 | drv->fw.default_calib[ucode_type].flow_trigger = |
399 | def_calib->calib.flow_trigger; | |
400 | drv->fw.default_calib[ucode_type].event_trigger = | |
401 | def_calib->calib.event_trigger; | |
402 | ||
ed8c8365 DS |
403 | return 0; |
404 | } | |
405 | ||
965974a6 | 406 | static int iwl_parse_v1_v2_firmware(struct iwl_drv *drv, |
0cedacc5 DS |
407 | const struct firmware *ucode_raw, |
408 | struct iwl_firmware_pieces *pieces) | |
15854ef9 JB |
409 | { |
410 | struct iwl_ucode_header *ucode = (void *)ucode_raw->data; | |
411 | u32 api_ver, hdr_size, build; | |
412 | char buildstr[25]; | |
413 | const u8 *src; | |
414 | ||
965974a6 JB |
415 | drv->fw.ucode_ver = le32_to_cpu(ucode->ver); |
416 | api_ver = IWL_UCODE_API(drv->fw.ucode_ver); | |
15854ef9 JB |
417 | |
418 | switch (api_ver) { | |
419 | default: | |
420 | hdr_size = 28; | |
421 | if (ucode_raw->size < hdr_size) { | |
965974a6 | 422 | IWL_ERR(drv, "File size too small!\n"); |
15854ef9 JB |
423 | return -EINVAL; |
424 | } | |
425 | build = le32_to_cpu(ucode->u.v2.build); | |
0cedacc5 DS |
426 | set_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_INST, |
427 | le32_to_cpu(ucode->u.v2.inst_size)); | |
428 | set_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_DATA, | |
429 | le32_to_cpu(ucode->u.v2.data_size)); | |
430 | set_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_INST, | |
431 | le32_to_cpu(ucode->u.v2.init_size)); | |
432 | set_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_DATA, | |
433 | le32_to_cpu(ucode->u.v2.init_data_size)); | |
15854ef9 JB |
434 | src = ucode->u.v2.data; |
435 | break; | |
436 | case 0: | |
437 | case 1: | |
438 | case 2: | |
439 | hdr_size = 24; | |
440 | if (ucode_raw->size < hdr_size) { | |
965974a6 | 441 | IWL_ERR(drv, "File size too small!\n"); |
15854ef9 JB |
442 | return -EINVAL; |
443 | } | |
444 | build = 0; | |
0cedacc5 DS |
445 | set_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_INST, |
446 | le32_to_cpu(ucode->u.v1.inst_size)); | |
447 | set_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_DATA, | |
448 | le32_to_cpu(ucode->u.v1.data_size)); | |
449 | set_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_INST, | |
450 | le32_to_cpu(ucode->u.v1.init_size)); | |
451 | set_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_DATA, | |
452 | le32_to_cpu(ucode->u.v1.init_data_size)); | |
15854ef9 JB |
453 | src = ucode->u.v1.data; |
454 | break; | |
455 | } | |
456 | ||
457 | if (build) | |
458 | sprintf(buildstr, " build %u%s", build, | |
965974a6 | 459 | (drv->fw_index == UCODE_EXPERIMENTAL_INDEX) |
15854ef9 JB |
460 | ? " (EXP)" : ""); |
461 | else | |
462 | buildstr[0] = '\0'; | |
463 | ||
965974a6 JB |
464 | snprintf(drv->fw.fw_version, |
465 | sizeof(drv->fw.fw_version), | |
15854ef9 | 466 | "%u.%u.%u.%u%s", |
965974a6 JB |
467 | IWL_UCODE_MAJOR(drv->fw.ucode_ver), |
468 | IWL_UCODE_MINOR(drv->fw.ucode_ver), | |
469 | IWL_UCODE_API(drv->fw.ucode_ver), | |
470 | IWL_UCODE_SERIAL(drv->fw.ucode_ver), | |
15854ef9 JB |
471 | buildstr); |
472 | ||
473 | /* Verify size of file vs. image size info in file's header */ | |
0cedacc5 DS |
474 | |
475 | if (ucode_raw->size != hdr_size + | |
476 | get_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_INST) + | |
477 | get_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_DATA) + | |
478 | get_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_INST) + | |
479 | get_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_DATA)) { | |
15854ef9 | 480 | |
965974a6 | 481 | IWL_ERR(drv, |
15854ef9 JB |
482 | "uCode file size %d does not match expected size\n", |
483 | (int)ucode_raw->size); | |
484 | return -EINVAL; | |
485 | } | |
486 | ||
15854ef9 | 487 | |
0cedacc5 DS |
488 | set_sec_data(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_INST, src); |
489 | src += get_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_INST); | |
490 | set_sec_offset(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_INST, | |
491 | IWLAGN_RTC_INST_LOWER_BOUND); | |
492 | set_sec_data(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_DATA, src); | |
493 | src += get_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_DATA); | |
494 | set_sec_offset(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_DATA, | |
495 | IWLAGN_RTC_DATA_LOWER_BOUND); | |
496 | set_sec_data(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_INST, src); | |
497 | src += get_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_INST); | |
498 | set_sec_offset(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_INST, | |
499 | IWLAGN_RTC_INST_LOWER_BOUND); | |
500 | set_sec_data(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_DATA, src); | |
501 | src += get_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_DATA); | |
502 | set_sec_offset(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_DATA, | |
503 | IWLAGN_RTC_DATA_LOWER_BOUND); | |
15854ef9 JB |
504 | return 0; |
505 | } | |
506 | ||
965974a6 | 507 | static int iwl_parse_tlv_firmware(struct iwl_drv *drv, |
15854ef9 | 508 | const struct firmware *ucode_raw, |
0cedacc5 | 509 | struct iwl_firmware_pieces *pieces, |
15854ef9 JB |
510 | struct iwl_ucode_capabilities *capa) |
511 | { | |
512 | struct iwl_tlv_ucode_header *ucode = (void *)ucode_raw->data; | |
513 | struct iwl_ucode_tlv *tlv; | |
514 | size_t len = ucode_raw->size; | |
515 | const u8 *data; | |
15854ef9 JB |
516 | u32 tlv_len; |
517 | enum iwl_ucode_tlv_type tlv_type; | |
518 | const u8 *tlv_data; | |
519 | char buildstr[25]; | |
520 | u32 build; | |
e2d6f4e7 | 521 | int num_of_cpus; |
15854ef9 JB |
522 | |
523 | if (len < sizeof(*ucode)) { | |
965974a6 | 524 | IWL_ERR(drv, "uCode has invalid length: %zd\n", len); |
15854ef9 JB |
525 | return -EINVAL; |
526 | } | |
527 | ||
528 | if (ucode->magic != cpu_to_le32(IWL_TLV_UCODE_MAGIC)) { | |
965974a6 | 529 | IWL_ERR(drv, "invalid uCode magic: 0X%x\n", |
15854ef9 JB |
530 | le32_to_cpu(ucode->magic)); |
531 | return -EINVAL; | |
532 | } | |
533 | ||
965974a6 | 534 | drv->fw.ucode_ver = le32_to_cpu(ucode->ver); |
15854ef9 JB |
535 | build = le32_to_cpu(ucode->build); |
536 | ||
537 | if (build) | |
538 | sprintf(buildstr, " build %u%s", build, | |
965974a6 | 539 | (drv->fw_index == UCODE_EXPERIMENTAL_INDEX) |
15854ef9 JB |
540 | ? " (EXP)" : ""); |
541 | else | |
542 | buildstr[0] = '\0'; | |
543 | ||
965974a6 JB |
544 | snprintf(drv->fw.fw_version, |
545 | sizeof(drv->fw.fw_version), | |
15854ef9 | 546 | "%u.%u.%u.%u%s", |
965974a6 JB |
547 | IWL_UCODE_MAJOR(drv->fw.ucode_ver), |
548 | IWL_UCODE_MINOR(drv->fw.ucode_ver), | |
549 | IWL_UCODE_API(drv->fw.ucode_ver), | |
550 | IWL_UCODE_SERIAL(drv->fw.ucode_ver), | |
15854ef9 JB |
551 | buildstr); |
552 | ||
553 | data = ucode->data; | |
554 | ||
555 | len -= sizeof(*ucode); | |
556 | ||
557 | while (len >= sizeof(*tlv)) { | |
15854ef9 JB |
558 | len -= sizeof(*tlv); |
559 | tlv = (void *)data; | |
560 | ||
561 | tlv_len = le32_to_cpu(tlv->length); | |
0479c19d | 562 | tlv_type = le32_to_cpu(tlv->type); |
15854ef9 JB |
563 | tlv_data = tlv->data; |
564 | ||
565 | if (len < tlv_len) { | |
965974a6 | 566 | IWL_ERR(drv, "invalid TLV len: %zd/%u\n", |
15854ef9 JB |
567 | len, tlv_len); |
568 | return -EINVAL; | |
569 | } | |
570 | len -= ALIGN(tlv_len, 4); | |
571 | data += sizeof(*tlv) + ALIGN(tlv_len, 4); | |
572 | ||
15854ef9 JB |
573 | switch (tlv_type) { |
574 | case IWL_UCODE_TLV_INST: | |
0cedacc5 DS |
575 | set_sec_data(pieces, IWL_UCODE_REGULAR, |
576 | IWL_UCODE_SECTION_INST, tlv_data); | |
577 | set_sec_size(pieces, IWL_UCODE_REGULAR, | |
578 | IWL_UCODE_SECTION_INST, tlv_len); | |
579 | set_sec_offset(pieces, IWL_UCODE_REGULAR, | |
580 | IWL_UCODE_SECTION_INST, | |
581 | IWLAGN_RTC_INST_LOWER_BOUND); | |
15854ef9 JB |
582 | break; |
583 | case IWL_UCODE_TLV_DATA: | |
0cedacc5 DS |
584 | set_sec_data(pieces, IWL_UCODE_REGULAR, |
585 | IWL_UCODE_SECTION_DATA, tlv_data); | |
586 | set_sec_size(pieces, IWL_UCODE_REGULAR, | |
587 | IWL_UCODE_SECTION_DATA, tlv_len); | |
588 | set_sec_offset(pieces, IWL_UCODE_REGULAR, | |
589 | IWL_UCODE_SECTION_DATA, | |
590 | IWLAGN_RTC_DATA_LOWER_BOUND); | |
15854ef9 JB |
591 | break; |
592 | case IWL_UCODE_TLV_INIT: | |
0cedacc5 DS |
593 | set_sec_data(pieces, IWL_UCODE_INIT, |
594 | IWL_UCODE_SECTION_INST, tlv_data); | |
595 | set_sec_size(pieces, IWL_UCODE_INIT, | |
596 | IWL_UCODE_SECTION_INST, tlv_len); | |
597 | set_sec_offset(pieces, IWL_UCODE_INIT, | |
598 | IWL_UCODE_SECTION_INST, | |
599 | IWLAGN_RTC_INST_LOWER_BOUND); | |
15854ef9 JB |
600 | break; |
601 | case IWL_UCODE_TLV_INIT_DATA: | |
0cedacc5 DS |
602 | set_sec_data(pieces, IWL_UCODE_INIT, |
603 | IWL_UCODE_SECTION_DATA, tlv_data); | |
604 | set_sec_size(pieces, IWL_UCODE_INIT, | |
605 | IWL_UCODE_SECTION_DATA, tlv_len); | |
606 | set_sec_offset(pieces, IWL_UCODE_INIT, | |
607 | IWL_UCODE_SECTION_DATA, | |
608 | IWLAGN_RTC_DATA_LOWER_BOUND); | |
15854ef9 JB |
609 | break; |
610 | case IWL_UCODE_TLV_BOOT: | |
965974a6 | 611 | IWL_ERR(drv, "Found unexpected BOOT ucode\n"); |
15854ef9 JB |
612 | break; |
613 | case IWL_UCODE_TLV_PROBE_MAX_LEN: | |
614 | if (tlv_len != sizeof(u32)) | |
615 | goto invalid_tlv_len; | |
616 | capa->max_probe_length = | |
617 | le32_to_cpup((__le32 *)tlv_data); | |
618 | break; | |
619 | case IWL_UCODE_TLV_PAN: | |
620 | if (tlv_len) | |
621 | goto invalid_tlv_len; | |
622 | capa->flags |= IWL_UCODE_TLV_FLAGS_PAN; | |
623 | break; | |
624 | case IWL_UCODE_TLV_FLAGS: | |
625 | /* must be at least one u32 */ | |
626 | if (tlv_len < sizeof(u32)) | |
627 | goto invalid_tlv_len; | |
628 | /* and a proper number of u32s */ | |
629 | if (tlv_len % sizeof(u32)) | |
630 | goto invalid_tlv_len; | |
631 | /* | |
632 | * This driver only reads the first u32 as | |
633 | * right now no more features are defined, | |
634 | * if that changes then either the driver | |
635 | * will not work with the new firmware, or | |
636 | * it'll not take advantage of new features. | |
637 | */ | |
638 | capa->flags = le32_to_cpup((__le32 *)tlv_data); | |
639 | break; | |
640 | case IWL_UCODE_TLV_INIT_EVTLOG_PTR: | |
641 | if (tlv_len != sizeof(u32)) | |
642 | goto invalid_tlv_len; | |
643 | pieces->init_evtlog_ptr = | |
644 | le32_to_cpup((__le32 *)tlv_data); | |
645 | break; | |
646 | case IWL_UCODE_TLV_INIT_EVTLOG_SIZE: | |
647 | if (tlv_len != sizeof(u32)) | |
648 | goto invalid_tlv_len; | |
649 | pieces->init_evtlog_size = | |
650 | le32_to_cpup((__le32 *)tlv_data); | |
651 | break; | |
652 | case IWL_UCODE_TLV_INIT_ERRLOG_PTR: | |
653 | if (tlv_len != sizeof(u32)) | |
654 | goto invalid_tlv_len; | |
655 | pieces->init_errlog_ptr = | |
656 | le32_to_cpup((__le32 *)tlv_data); | |
657 | break; | |
658 | case IWL_UCODE_TLV_RUNT_EVTLOG_PTR: | |
659 | if (tlv_len != sizeof(u32)) | |
660 | goto invalid_tlv_len; | |
661 | pieces->inst_evtlog_ptr = | |
662 | le32_to_cpup((__le32 *)tlv_data); | |
663 | break; | |
664 | case IWL_UCODE_TLV_RUNT_EVTLOG_SIZE: | |
665 | if (tlv_len != sizeof(u32)) | |
666 | goto invalid_tlv_len; | |
667 | pieces->inst_evtlog_size = | |
668 | le32_to_cpup((__le32 *)tlv_data); | |
669 | break; | |
670 | case IWL_UCODE_TLV_RUNT_ERRLOG_PTR: | |
671 | if (tlv_len != sizeof(u32)) | |
672 | goto invalid_tlv_len; | |
673 | pieces->inst_errlog_ptr = | |
674 | le32_to_cpup((__le32 *)tlv_data); | |
675 | break; | |
676 | case IWL_UCODE_TLV_ENHANCE_SENS_TBL: | |
677 | if (tlv_len) | |
678 | goto invalid_tlv_len; | |
965974a6 | 679 | drv->fw.enhance_sensitivity_table = true; |
15854ef9 JB |
680 | break; |
681 | case IWL_UCODE_TLV_WOWLAN_INST: | |
0cedacc5 DS |
682 | set_sec_data(pieces, IWL_UCODE_WOWLAN, |
683 | IWL_UCODE_SECTION_INST, tlv_data); | |
684 | set_sec_size(pieces, IWL_UCODE_WOWLAN, | |
685 | IWL_UCODE_SECTION_INST, tlv_len); | |
686 | set_sec_offset(pieces, IWL_UCODE_WOWLAN, | |
687 | IWL_UCODE_SECTION_INST, | |
688 | IWLAGN_RTC_INST_LOWER_BOUND); | |
15854ef9 JB |
689 | break; |
690 | case IWL_UCODE_TLV_WOWLAN_DATA: | |
0cedacc5 DS |
691 | set_sec_data(pieces, IWL_UCODE_WOWLAN, |
692 | IWL_UCODE_SECTION_DATA, tlv_data); | |
693 | set_sec_size(pieces, IWL_UCODE_WOWLAN, | |
694 | IWL_UCODE_SECTION_DATA, tlv_len); | |
695 | set_sec_offset(pieces, IWL_UCODE_WOWLAN, | |
696 | IWL_UCODE_SECTION_DATA, | |
697 | IWLAGN_RTC_DATA_LOWER_BOUND); | |
15854ef9 JB |
698 | break; |
699 | case IWL_UCODE_TLV_PHY_CALIBRATION_SIZE: | |
700 | if (tlv_len != sizeof(u32)) | |
701 | goto invalid_tlv_len; | |
702 | capa->standard_phy_calibration_size = | |
703 | le32_to_cpup((__le32 *)tlv_data); | |
704 | break; | |
ed8c8365 DS |
705 | case IWL_UCODE_TLV_SEC_RT: |
706 | iwl_store_ucode_sec(pieces, tlv_data, IWL_UCODE_REGULAR, | |
707 | tlv_len); | |
4db2c9ae | 708 | drv->fw.mvm_fw = true; |
ed8c8365 DS |
709 | break; |
710 | case IWL_UCODE_TLV_SEC_INIT: | |
711 | iwl_store_ucode_sec(pieces, tlv_data, IWL_UCODE_INIT, | |
712 | tlv_len); | |
4db2c9ae | 713 | drv->fw.mvm_fw = true; |
ed8c8365 DS |
714 | break; |
715 | case IWL_UCODE_TLV_SEC_WOWLAN: | |
716 | iwl_store_ucode_sec(pieces, tlv_data, IWL_UCODE_WOWLAN, | |
717 | tlv_len); | |
4db2c9ae | 718 | drv->fw.mvm_fw = true; |
ed8c8365 DS |
719 | break; |
720 | case IWL_UCODE_TLV_DEF_CALIB: | |
721 | if (tlv_len != sizeof(struct iwl_tlv_calib_data)) | |
722 | goto invalid_tlv_len; | |
723 | if (iwl_set_default_calib(drv, tlv_data)) | |
724 | goto tlv_error; | |
725 | break; | |
726 | case IWL_UCODE_TLV_PHY_SKU: | |
727 | if (tlv_len != sizeof(u32)) | |
728 | goto invalid_tlv_len; | |
729 | drv->fw.phy_config = le32_to_cpup((__le32 *)tlv_data); | |
730 | break; | |
e2d6f4e7 EH |
731 | case IWL_UCODE_TLV_SECURE_SEC_RT: |
732 | iwl_store_ucode_sec(pieces, tlv_data, IWL_UCODE_REGULAR, | |
733 | tlv_len); | |
734 | drv->fw.mvm_fw = true; | |
735 | drv->fw.img[IWL_UCODE_REGULAR].is_secure = true; | |
736 | break; | |
737 | case IWL_UCODE_TLV_SECURE_SEC_INIT: | |
738 | iwl_store_ucode_sec(pieces, tlv_data, IWL_UCODE_INIT, | |
739 | tlv_len); | |
740 | drv->fw.mvm_fw = true; | |
741 | drv->fw.img[IWL_UCODE_INIT].is_secure = true; | |
742 | break; | |
743 | case IWL_UCODE_TLV_SECURE_SEC_WOWLAN: | |
744 | iwl_store_ucode_sec(pieces, tlv_data, IWL_UCODE_WOWLAN, | |
745 | tlv_len); | |
746 | drv->fw.mvm_fw = true; | |
747 | drv->fw.img[IWL_UCODE_WOWLAN].is_secure = true; | |
748 | break; | |
749 | case IWL_UCODE_TLV_NUM_OF_CPU: | |
750 | if (tlv_len != sizeof(u32)) | |
751 | goto invalid_tlv_len; | |
752 | num_of_cpus = | |
753 | le32_to_cpup((__le32 *)tlv_data); | |
754 | ||
755 | if (num_of_cpus == 2) { | |
756 | drv->fw.img[IWL_UCODE_REGULAR].is_dual_cpus = | |
757 | true; | |
758 | drv->fw.img[IWL_UCODE_INIT].is_dual_cpus = | |
759 | true; | |
760 | drv->fw.img[IWL_UCODE_WOWLAN].is_dual_cpus = | |
761 | true; | |
762 | } else if ((num_of_cpus > 2) || (num_of_cpus < 1)) { | |
763 | IWL_ERR(drv, "Driver support upto 2 CPUs\n"); | |
764 | return -EINVAL; | |
765 | } | |
766 | break; | |
e36e5433 MS |
767 | case IWL_UCODE_TLV_CSCHEME: |
768 | if (iwl_store_cscheme(&drv->fw, tlv_data, tlv_len)) | |
769 | goto invalid_tlv_len; | |
770 | break; | |
15854ef9 | 771 | default: |
965974a6 | 772 | IWL_DEBUG_INFO(drv, "unknown TLV: %d\n", tlv_type); |
15854ef9 JB |
773 | break; |
774 | } | |
775 | } | |
776 | ||
777 | if (len) { | |
965974a6 JB |
778 | IWL_ERR(drv, "invalid TLV after parsing: %zd\n", len); |
779 | iwl_print_hex_dump(drv, IWL_DL_FW, (u8 *)data, len); | |
15854ef9 JB |
780 | return -EINVAL; |
781 | } | |
782 | ||
783 | return 0; | |
784 | ||
785 | invalid_tlv_len: | |
965974a6 | 786 | IWL_ERR(drv, "TLV %d has invalid size: %u\n", tlv_type, tlv_len); |
ed8c8365 | 787 | tlv_error: |
965974a6 | 788 | iwl_print_hex_dump(drv, IWL_DL_FW, tlv_data, tlv_len); |
15854ef9 JB |
789 | |
790 | return -EINVAL; | |
791 | } | |
792 | ||
75813bde JB |
793 | static int iwl_alloc_ucode(struct iwl_drv *drv, |
794 | struct iwl_firmware_pieces *pieces, | |
795 | enum iwl_ucode_type type) | |
6dfa8d01 DS |
796 | { |
797 | int i; | |
798 | for (i = 0; | |
799 | i < IWL_UCODE_SECTION_MAX && get_sec_size(pieces, type, i); | |
800 | i++) | |
801 | if (iwl_alloc_fw_desc(drv, &(drv->fw.img[type].sec[i]), | |
75813bde JB |
802 | get_sec(pieces, type, i))) |
803 | return -ENOMEM; | |
6dfa8d01 DS |
804 | return 0; |
805 | } | |
806 | ||
807 | static int validate_sec_sizes(struct iwl_drv *drv, | |
808 | struct iwl_firmware_pieces *pieces, | |
809 | const struct iwl_cfg *cfg) | |
810 | { | |
811 | IWL_DEBUG_INFO(drv, "f/w package hdr runtime inst size = %Zd\n", | |
812 | get_sec_size(pieces, IWL_UCODE_REGULAR, | |
813 | IWL_UCODE_SECTION_INST)); | |
814 | IWL_DEBUG_INFO(drv, "f/w package hdr runtime data size = %Zd\n", | |
815 | get_sec_size(pieces, IWL_UCODE_REGULAR, | |
816 | IWL_UCODE_SECTION_DATA)); | |
817 | IWL_DEBUG_INFO(drv, "f/w package hdr init inst size = %Zd\n", | |
818 | get_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_INST)); | |
819 | IWL_DEBUG_INFO(drv, "f/w package hdr init data size = %Zd\n", | |
820 | get_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_DATA)); | |
821 | ||
822 | /* Verify that uCode images will fit in card's SRAM. */ | |
823 | if (get_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_INST) > | |
824 | cfg->max_inst_size) { | |
825 | IWL_ERR(drv, "uCode instr len %Zd too large to fit in\n", | |
826 | get_sec_size(pieces, IWL_UCODE_REGULAR, | |
827 | IWL_UCODE_SECTION_INST)); | |
828 | return -1; | |
829 | } | |
830 | ||
831 | if (get_sec_size(pieces, IWL_UCODE_REGULAR, IWL_UCODE_SECTION_DATA) > | |
832 | cfg->max_data_size) { | |
833 | IWL_ERR(drv, "uCode data len %Zd too large to fit in\n", | |
834 | get_sec_size(pieces, IWL_UCODE_REGULAR, | |
835 | IWL_UCODE_SECTION_DATA)); | |
836 | return -1; | |
837 | } | |
838 | ||
839 | if (get_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_INST) > | |
840 | cfg->max_inst_size) { | |
841 | IWL_ERR(drv, "uCode init instr len %Zd too large to fit in\n", | |
842 | get_sec_size(pieces, IWL_UCODE_INIT, | |
843 | IWL_UCODE_SECTION_INST)); | |
844 | return -1; | |
845 | } | |
846 | ||
847 | if (get_sec_size(pieces, IWL_UCODE_INIT, IWL_UCODE_SECTION_DATA) > | |
848 | cfg->max_data_size) { | |
849 | IWL_ERR(drv, "uCode init data len %Zd too large to fit in\n", | |
850 | get_sec_size(pieces, IWL_UCODE_REGULAR, | |
851 | IWL_UCODE_SECTION_DATA)); | |
852 | return -1; | |
853 | } | |
854 | return 0; | |
855 | } | |
856 | ||
9da987ac MV |
857 | static struct iwl_op_mode * |
858 | _iwl_op_mode_start(struct iwl_drv *drv, struct iwlwifi_opmode_table *op) | |
859 | { | |
860 | const struct iwl_op_mode_ops *ops = op->ops; | |
861 | struct dentry *dbgfs_dir = NULL; | |
862 | struct iwl_op_mode *op_mode = NULL; | |
863 | ||
864 | #ifdef CONFIG_IWLWIFI_DEBUGFS | |
865 | drv->dbgfs_op_mode = debugfs_create_dir(op->name, | |
866 | drv->dbgfs_drv); | |
867 | if (!drv->dbgfs_op_mode) { | |
868 | IWL_ERR(drv, | |
869 | "failed to create opmode debugfs directory\n"); | |
870 | return op_mode; | |
871 | } | |
872 | dbgfs_dir = drv->dbgfs_op_mode; | |
873 | #endif | |
874 | ||
875 | op_mode = ops->start(drv->trans, drv->cfg, &drv->fw, dbgfs_dir); | |
876 | ||
877 | #ifdef CONFIG_IWLWIFI_DEBUGFS | |
878 | if (!op_mode) { | |
879 | debugfs_remove_recursive(drv->dbgfs_op_mode); | |
880 | drv->dbgfs_op_mode = NULL; | |
881 | } | |
882 | #endif | |
883 | ||
884 | return op_mode; | |
885 | } | |
886 | ||
887 | static void _iwl_op_mode_stop(struct iwl_drv *drv) | |
888 | { | |
889 | /* op_mode can be NULL if its start failed */ | |
890 | if (drv->op_mode) { | |
891 | iwl_op_mode_stop(drv->op_mode); | |
892 | drv->op_mode = NULL; | |
893 | ||
894 | #ifdef CONFIG_IWLWIFI_DEBUGFS | |
895 | debugfs_remove_recursive(drv->dbgfs_op_mode); | |
896 | drv->dbgfs_op_mode = NULL; | |
897 | #endif | |
898 | } | |
899 | } | |
900 | ||
15854ef9 | 901 | /** |
1c8e11e1 | 902 | * iwl_req_fw_callback - callback when firmware was loaded |
15854ef9 JB |
903 | * |
904 | * If loaded successfully, copies the firmware into buffers | |
905 | * for the card to fetch (via DMA). | |
906 | */ | |
1c8e11e1 | 907 | static void iwl_req_fw_callback(const struct firmware *ucode_raw, void *context) |
15854ef9 | 908 | { |
965974a6 | 909 | struct iwl_drv *drv = context; |
965974a6 | 910 | struct iwl_fw *fw = &drv->fw; |
15854ef9 | 911 | struct iwl_ucode_header *ucode; |
cc5f7e39 | 912 | struct iwlwifi_opmode_table *op; |
15854ef9 | 913 | int err; |
0cedacc5 | 914 | struct iwl_firmware_pieces pieces; |
68f360dc EG |
915 | const unsigned int api_max = drv->cfg->ucode_api_max; |
916 | unsigned int api_ok = drv->cfg->ucode_api_ok; | |
917 | const unsigned int api_min = drv->cfg->ucode_api_min; | |
15854ef9 | 918 | u32 api_ver; |
6dfa8d01 | 919 | int i; |
d4b10483 | 920 | bool load_module = false; |
15854ef9 | 921 | |
66140adc | 922 | fw->ucode_capa.max_probe_length = IWL_DEFAULT_MAX_PROBE_LENGTH; |
15854ef9 JB |
923 | fw->ucode_capa.standard_phy_calibration_size = |
924 | IWL_DEFAULT_STANDARD_PHY_CALIBRATE_TBL_SIZE; | |
925 | ||
926 | if (!api_ok) | |
927 | api_ok = api_max; | |
928 | ||
929 | memset(&pieces, 0, sizeof(pieces)); | |
930 | ||
931 | if (!ucode_raw) { | |
965974a6 JB |
932 | if (drv->fw_index <= api_ok) |
933 | IWL_ERR(drv, | |
15854ef9 | 934 | "request for firmware file '%s' failed.\n", |
965974a6 | 935 | drv->firmware_name); |
15854ef9 JB |
936 | goto try_again; |
937 | } | |
938 | ||
965974a6 JB |
939 | IWL_DEBUG_INFO(drv, "Loaded firmware file '%s' (%zd bytes).\n", |
940 | drv->firmware_name, ucode_raw->size); | |
15854ef9 JB |
941 | |
942 | /* Make sure that we got at least the API version number */ | |
943 | if (ucode_raw->size < 4) { | |
965974a6 | 944 | IWL_ERR(drv, "File size way too small!\n"); |
15854ef9 JB |
945 | goto try_again; |
946 | } | |
947 | ||
948 | /* Data from ucode file: header followed by uCode images */ | |
949 | ucode = (struct iwl_ucode_header *)ucode_raw->data; | |
950 | ||
951 | if (ucode->ver) | |
965974a6 | 952 | err = iwl_parse_v1_v2_firmware(drv, ucode_raw, &pieces); |
15854ef9 | 953 | else |
965974a6 | 954 | err = iwl_parse_tlv_firmware(drv, ucode_raw, &pieces, |
15854ef9 JB |
955 | &fw->ucode_capa); |
956 | ||
957 | if (err) | |
958 | goto try_again; | |
959 | ||
965974a6 | 960 | api_ver = IWL_UCODE_API(drv->fw.ucode_ver); |
15854ef9 JB |
961 | |
962 | /* | |
963 | * api_ver should match the api version forming part of the | |
964 | * firmware filename ... but we don't check for that and only rely | |
965 | * on the API version read from firmware header from here on forward | |
966 | */ | |
967 | /* no api version check required for experimental uCode */ | |
965974a6 | 968 | if (drv->fw_index != UCODE_EXPERIMENTAL_INDEX) { |
15854ef9 | 969 | if (api_ver < api_min || api_ver > api_max) { |
965974a6 | 970 | IWL_ERR(drv, |
15854ef9 JB |
971 | "Driver unable to support your firmware API. " |
972 | "Driver supports v%u, firmware is v%u.\n", | |
973 | api_max, api_ver); | |
974 | goto try_again; | |
975 | } | |
976 | ||
977 | if (api_ver < api_ok) { | |
978 | if (api_ok != api_max) | |
965974a6 | 979 | IWL_ERR(drv, "Firmware has old API version, " |
15854ef9 JB |
980 | "expected v%u through v%u, got v%u.\n", |
981 | api_ok, api_max, api_ver); | |
982 | else | |
965974a6 | 983 | IWL_ERR(drv, "Firmware has old API version, " |
15854ef9 JB |
984 | "expected v%u, got v%u.\n", |
985 | api_max, api_ver); | |
965974a6 | 986 | IWL_ERR(drv, "New firmware can be obtained from " |
15854ef9 JB |
987 | "http://www.intellinuxwireless.org/.\n"); |
988 | } | |
989 | } | |
990 | ||
4db2c9ae DS |
991 | /* |
992 | * In mvm uCode there is no difference between data and instructions | |
993 | * sections. | |
994 | */ | |
68f360dc | 995 | if (!fw->mvm_fw && validate_sec_sizes(drv, &pieces, drv->cfg)) |
15854ef9 | 996 | goto try_again; |
15854ef9 JB |
997 | |
998 | /* Allocate ucode buffers for card's bus-master loading ... */ | |
999 | ||
1000 | /* Runtime instructions and 2 copies of data: | |
1001 | * 1) unmodified from disk | |
1002 | * 2) backup cache for save/restore during power-downs */ | |
6dfa8d01 | 1003 | for (i = 0; i < IWL_UCODE_TYPE_MAX; i++) |
75813bde JB |
1004 | if (iwl_alloc_ucode(drv, &pieces, i)) |
1005 | goto out_free_fw; | |
15854ef9 JB |
1006 | |
1007 | /* Now that we can no longer fail, copy information */ | |
1008 | ||
1009 | /* | |
1010 | * The (size - 16) / 12 formula is based on the information recorded | |
1011 | * for each event, which is of mode 1 (including timestamp) for all | |
1012 | * new microcodes that include this information. | |
1013 | */ | |
0692fe41 | 1014 | fw->init_evtlog_ptr = pieces.init_evtlog_ptr; |
15854ef9 | 1015 | if (pieces.init_evtlog_size) |
0692fe41 | 1016 | fw->init_evtlog_size = (pieces.init_evtlog_size - 16)/12; |
15854ef9 | 1017 | else |
0692fe41 | 1018 | fw->init_evtlog_size = |
68f360dc | 1019 | drv->cfg->base_params->max_event_log_size; |
0692fe41 JB |
1020 | fw->init_errlog_ptr = pieces.init_errlog_ptr; |
1021 | fw->inst_evtlog_ptr = pieces.inst_evtlog_ptr; | |
15854ef9 | 1022 | if (pieces.inst_evtlog_size) |
0692fe41 | 1023 | fw->inst_evtlog_size = (pieces.inst_evtlog_size - 16)/12; |
15854ef9 | 1024 | else |
0692fe41 | 1025 | fw->inst_evtlog_size = |
68f360dc | 1026 | drv->cfg->base_params->max_event_log_size; |
0692fe41 | 1027 | fw->inst_errlog_ptr = pieces.inst_errlog_ptr; |
15854ef9 JB |
1028 | |
1029 | /* | |
1030 | * figure out the offset of chain noise reset and gain commands | |
1031 | * base on the size of standard phy calibration commands table size | |
1032 | */ | |
1033 | if (fw->ucode_capa.standard_phy_calibration_size > | |
1034 | IWL_MAX_PHY_CALIBRATE_TBL_SIZE) | |
1035 | fw->ucode_capa.standard_phy_calibration_size = | |
1036 | IWL_MAX_STANDARD_PHY_CALIBRATE_TBL_SIZE; | |
1037 | ||
1038 | /* We have our copies now, allow OS release its copies */ | |
1039 | release_firmware(ucode_raw); | |
15854ef9 | 1040 | |
ff1ffb85 | 1041 | mutex_lock(&iwlwifi_opmode_table_mtx); |
8ca151b5 JB |
1042 | if (fw->mvm_fw) |
1043 | op = &iwlwifi_opmode_table[MVM_OP_MODE]; | |
1044 | else | |
1045 | op = &iwlwifi_opmode_table[DVM_OP_MODE]; | |
15854ef9 | 1046 | |
2b2719c7 JB |
1047 | IWL_INFO(drv, "loaded firmware version %s op_mode %s\n", |
1048 | drv->fw.fw_version, op->name); | |
1049 | ||
cc5f7e39 DF |
1050 | /* add this device to the list of devices using this op_mode */ |
1051 | list_add_tail(&drv->list, &op->drv); | |
1052 | ||
1053 | if (op->ops) { | |
9da987ac | 1054 | drv->op_mode = _iwl_op_mode_start(drv, op); |
7c9c46c1 | 1055 | |
daf67ce8 DC |
1056 | if (!drv->op_mode) { |
1057 | mutex_unlock(&iwlwifi_opmode_table_mtx); | |
7c9c46c1 | 1058 | goto out_unbind; |
daf67ce8 | 1059 | } |
cc5f7e39 | 1060 | } else { |
d4b10483 | 1061 | load_module = true; |
cc5f7e39 | 1062 | } |
ff1ffb85 | 1063 | mutex_unlock(&iwlwifi_opmode_table_mtx); |
15854ef9 | 1064 | |
f69a23b7 JB |
1065 | /* |
1066 | * Complete the firmware request last so that | |
1067 | * a driver unbind (stop) doesn't run while we | |
1068 | * are doing the start() above. | |
1069 | */ | |
1070 | complete(&drv->request_firmware_complete); | |
d4b10483 JB |
1071 | |
1072 | /* | |
1073 | * Load the module last so we don't block anything | |
1074 | * else from proceeding if the module fails to load | |
1075 | * or hangs loading. | |
1076 | */ | |
1618b2b0 JB |
1077 | if (load_module) { |
1078 | err = request_module("%s", op->name); | |
8edf3fd6 | 1079 | #ifdef CONFIG_IWLWIFI_OPMODE_MODULAR |
1618b2b0 JB |
1080 | if (err) |
1081 | IWL_ERR(drv, | |
1082 | "failed to load module %s (error %d), is dynamic loading enabled?\n", | |
1083 | op->name, err); | |
8edf3fd6 | 1084 | #endif |
1618b2b0 | 1085 | } |
15854ef9 JB |
1086 | return; |
1087 | ||
1088 | try_again: | |
1089 | /* try next, if any */ | |
1090 | release_firmware(ucode_raw); | |
965974a6 | 1091 | if (iwl_request_firmware(drv, false)) |
15854ef9 JB |
1092 | goto out_unbind; |
1093 | return; | |
1094 | ||
75813bde | 1095 | out_free_fw: |
965974a6 JB |
1096 | IWL_ERR(drv, "failed to allocate pci memory\n"); |
1097 | iwl_dealloc_ucode(drv); | |
15854ef9 JB |
1098 | release_firmware(ucode_raw); |
1099 | out_unbind: | |
965974a6 | 1100 | complete(&drv->request_firmware_complete); |
93faaeea | 1101 | device_release_driver(drv->trans->dev); |
15854ef9 JB |
1102 | } |
1103 | ||
87ce05a2 | 1104 | struct iwl_drv *iwl_drv_start(struct iwl_trans *trans, |
9130bab1 | 1105 | const struct iwl_cfg *cfg) |
5c58edc6 | 1106 | { |
965974a6 | 1107 | struct iwl_drv *drv; |
5c58edc6 EG |
1108 | int ret; |
1109 | ||
965974a6 | 1110 | drv = kzalloc(sizeof(*drv), GFP_KERNEL); |
eafe25e0 LC |
1111 | if (!drv) { |
1112 | ret = -ENOMEM; | |
1113 | goto err; | |
1114 | } | |
c15797e6 | 1115 | |
9130bab1 | 1116 | drv->trans = trans; |
4b9844f5 | 1117 | drv->dev = trans->dev; |
68f360dc | 1118 | drv->cfg = cfg; |
5c58edc6 | 1119 | |
965974a6 | 1120 | init_completion(&drv->request_firmware_complete); |
ff1ffb85 | 1121 | INIT_LIST_HEAD(&drv->list); |
5c58edc6 | 1122 | |
9da987ac MV |
1123 | #ifdef CONFIG_IWLWIFI_DEBUGFS |
1124 | /* Create the device debugfs entries. */ | |
1125 | drv->dbgfs_drv = debugfs_create_dir(dev_name(trans->dev), | |
1126 | iwl_dbgfs_root); | |
1127 | ||
1128 | if (!drv->dbgfs_drv) { | |
1129 | IWL_ERR(drv, "failed to create debugfs directory\n"); | |
59f547ac | 1130 | ret = -ENOMEM; |
9da987ac MV |
1131 | goto err_free_drv; |
1132 | } | |
1133 | ||
1134 | /* Create transport layer debugfs dir */ | |
1135 | drv->trans->dbgfs_dir = debugfs_create_dir("trans", drv->dbgfs_drv); | |
1136 | ||
1137 | if (!drv->trans->dbgfs_dir) { | |
1138 | IWL_ERR(drv, "failed to create transport debugfs directory\n"); | |
59f547ac | 1139 | ret = -ENOMEM; |
9da987ac MV |
1140 | goto err_free_dbgfs; |
1141 | } | |
1142 | #endif | |
1143 | ||
965974a6 | 1144 | ret = iwl_request_firmware(drv, true); |
5c58edc6 | 1145 | if (ret) { |
c15797e6 | 1146 | IWL_ERR(trans, "Couldn't request the fw\n"); |
9da987ac | 1147 | goto err_fw; |
5c58edc6 EG |
1148 | } |
1149 | ||
9da987ac MV |
1150 | return drv; |
1151 | ||
1152 | err_fw: | |
1153 | #ifdef CONFIG_IWLWIFI_DEBUGFS | |
1154 | err_free_dbgfs: | |
1155 | debugfs_remove_recursive(drv->dbgfs_drv); | |
1156 | err_free_drv: | |
1157 | #endif | |
1158 | kfree(drv); | |
eafe25e0 | 1159 | err: |
59f547ac | 1160 | return ERR_PTR(ret); |
5c58edc6 EG |
1161 | } |
1162 | ||
9130bab1 | 1163 | void iwl_drv_stop(struct iwl_drv *drv) |
07590f08 | 1164 | { |
965974a6 | 1165 | wait_for_completion(&drv->request_firmware_complete); |
2e7eb117 | 1166 | |
9da987ac | 1167 | _iwl_op_mode_stop(drv); |
07590f08 | 1168 | |
965974a6 | 1169 | iwl_dealloc_ucode(drv); |
7db5b989 | 1170 | |
ff1ffb85 JB |
1171 | mutex_lock(&iwlwifi_opmode_table_mtx); |
1172 | /* | |
1173 | * List is empty (this item wasn't added) | |
1174 | * when firmware loading failed -- in that | |
1175 | * case we can't remove it from any list. | |
1176 | */ | |
1177 | if (!list_empty(&drv->list)) | |
1178 | list_del(&drv->list); | |
1179 | mutex_unlock(&iwlwifi_opmode_table_mtx); | |
1180 | ||
9da987ac MV |
1181 | #ifdef CONFIG_IWLWIFI_DEBUGFS |
1182 | debugfs_remove_recursive(drv->dbgfs_drv); | |
1183 | #endif | |
1184 | ||
965974a6 | 1185 | kfree(drv); |
07590f08 | 1186 | } |
65de7e84 JB |
1187 | |
1188 | ||
1189 | /* shared module parameters */ | |
1190 | struct iwl_mod_params iwlwifi_mod_params = { | |
490953ac | 1191 | .restart_fw = true, |
65de7e84 JB |
1192 | .bt_coex_active = true, |
1193 | .power_level = IWL_POWER_INDEX_1, | |
020c8767 | 1194 | .wd_disable = true, |
65de7e84 JB |
1195 | /* the rest are 0 by default */ |
1196 | }; | |
48e29340 | 1197 | IWL_EXPORT_SYMBOL(iwlwifi_mod_params); |
cc5f7e39 DF |
1198 | |
1199 | int iwl_opmode_register(const char *name, const struct iwl_op_mode_ops *ops) | |
1200 | { | |
1201 | int i; | |
1202 | struct iwl_drv *drv; | |
9da987ac | 1203 | struct iwlwifi_opmode_table *op; |
cc5f7e39 | 1204 | |
ff1ffb85 | 1205 | mutex_lock(&iwlwifi_opmode_table_mtx); |
cc5f7e39 | 1206 | for (i = 0; i < ARRAY_SIZE(iwlwifi_opmode_table); i++) { |
9da987ac MV |
1207 | op = &iwlwifi_opmode_table[i]; |
1208 | if (strcmp(op->name, name)) | |
cc5f7e39 | 1209 | continue; |
9da987ac MV |
1210 | op->ops = ops; |
1211 | /* TODO: need to handle exceptional case */ | |
1212 | list_for_each_entry(drv, &op->drv, list) | |
1213 | drv->op_mode = _iwl_op_mode_start(drv, op); | |
1214 | ||
ff1ffb85 | 1215 | mutex_unlock(&iwlwifi_opmode_table_mtx); |
cc5f7e39 DF |
1216 | return 0; |
1217 | } | |
ff1ffb85 | 1218 | mutex_unlock(&iwlwifi_opmode_table_mtx); |
cc5f7e39 DF |
1219 | return -EIO; |
1220 | } | |
48e29340 | 1221 | IWL_EXPORT_SYMBOL(iwl_opmode_register); |
cc5f7e39 DF |
1222 | |
1223 | void iwl_opmode_deregister(const char *name) | |
1224 | { | |
1225 | int i; | |
1226 | struct iwl_drv *drv; | |
1227 | ||
ff1ffb85 | 1228 | mutex_lock(&iwlwifi_opmode_table_mtx); |
cc5f7e39 DF |
1229 | for (i = 0; i < ARRAY_SIZE(iwlwifi_opmode_table); i++) { |
1230 | if (strcmp(iwlwifi_opmode_table[i].name, name)) | |
1231 | continue; | |
1232 | iwlwifi_opmode_table[i].ops = NULL; | |
1233 | ||
1234 | /* call the stop routine for all devices */ | |
9da987ac MV |
1235 | list_for_each_entry(drv, &iwlwifi_opmode_table[i].drv, list) |
1236 | _iwl_op_mode_stop(drv); | |
1237 | ||
ff1ffb85 | 1238 | mutex_unlock(&iwlwifi_opmode_table_mtx); |
cc5f7e39 DF |
1239 | return; |
1240 | } | |
ff1ffb85 | 1241 | mutex_unlock(&iwlwifi_opmode_table_mtx); |
cc5f7e39 | 1242 | } |
48e29340 | 1243 | IWL_EXPORT_SYMBOL(iwl_opmode_deregister); |
cc5f7e39 DF |
1244 | |
1245 | static int __init iwl_drv_init(void) | |
1246 | { | |
1247 | int i; | |
1248 | ||
ff1ffb85 JB |
1249 | mutex_init(&iwlwifi_opmode_table_mtx); |
1250 | ||
cc5f7e39 DF |
1251 | for (i = 0; i < ARRAY_SIZE(iwlwifi_opmode_table); i++) |
1252 | INIT_LIST_HEAD(&iwlwifi_opmode_table[i].drv); | |
1253 | ||
1254 | pr_info(DRV_DESCRIPTION ", " DRV_VERSION "\n"); | |
1255 | pr_info(DRV_COPYRIGHT "\n"); | |
1256 | ||
9da987ac MV |
1257 | #ifdef CONFIG_IWLWIFI_DEBUGFS |
1258 | /* Create the root of iwlwifi debugfs subsystem. */ | |
1259 | iwl_dbgfs_root = debugfs_create_dir(DRV_NAME, NULL); | |
1260 | ||
1261 | if (!iwl_dbgfs_root) | |
1262 | return -EFAULT; | |
1263 | #endif | |
1264 | ||
cc5f7e39 DF |
1265 | return iwl_pci_register_driver(); |
1266 | } | |
1267 | module_init(iwl_drv_init); | |
1268 | ||
1269 | static void __exit iwl_drv_exit(void) | |
1270 | { | |
1271 | iwl_pci_unregister_driver(); | |
9da987ac MV |
1272 | |
1273 | #ifdef CONFIG_IWLWIFI_DEBUGFS | |
1274 | debugfs_remove_recursive(iwl_dbgfs_root); | |
1275 | #endif | |
cc5f7e39 DF |
1276 | } |
1277 | module_exit(iwl_drv_exit); | |
65de7e84 JB |
1278 | |
1279 | #ifdef CONFIG_IWLWIFI_DEBUG | |
1280 | module_param_named(debug, iwlwifi_mod_params.debug_level, uint, | |
1281 | S_IRUGO | S_IWUSR); | |
1282 | MODULE_PARM_DESC(debug, "debug output mask"); | |
1283 | #endif | |
1284 | ||
1285 | module_param_named(swcrypto, iwlwifi_mod_params.sw_crypto, int, S_IRUGO); | |
1286 | MODULE_PARM_DESC(swcrypto, "using crypto in software (default 0 [hardware])"); | |
1287 | module_param_named(11n_disable, iwlwifi_mod_params.disable_11n, uint, S_IRUGO); | |
1288 | MODULE_PARM_DESC(11n_disable, | |
205e2210 | 1289 | "disable 11n functionality, bitmap: 1: full, 2: disable agg TX, 4: disable agg RX, 8 enable agg TX"); |
65de7e84 JB |
1290 | module_param_named(amsdu_size_8K, iwlwifi_mod_params.amsdu_size_8K, |
1291 | int, S_IRUGO); | |
aed7d9ac | 1292 | MODULE_PARM_DESC(amsdu_size_8K, "enable 8K amsdu size (default 0)"); |
490953ac EG |
1293 | module_param_named(fw_restart, iwlwifi_mod_params.restart_fw, bool, S_IRUGO); |
1294 | MODULE_PARM_DESC(fw_restart, "restart firmware in case of error (default true)"); | |
65de7e84 JB |
1295 | |
1296 | module_param_named(antenna_coupling, iwlwifi_mod_params.ant_coupling, | |
1297 | int, S_IRUGO); | |
1298 | MODULE_PARM_DESC(antenna_coupling, | |
1299 | "specify antenna coupling in dB (defualt: 0 dB)"); | |
1300 | ||
65de7e84 JB |
1301 | module_param_named(wd_disable, iwlwifi_mod_params.wd_disable, int, S_IRUGO); |
1302 | MODULE_PARM_DESC(wd_disable, | |
1303 | "Disable stuck queue watchdog timer 0=system default, " | |
1304 | "1=disable, 2=enable (default: 0)"); | |
1305 | ||
1214755c EH |
1306 | module_param_named(nvm_file, iwlwifi_mod_params.nvm_file, charp, S_IRUGO); |
1307 | MODULE_PARM_DESC(nvm_file, "NVM file name"); | |
1308 | ||
65de7e84 JB |
1309 | /* |
1310 | * set bt_coex_active to true, uCode will do kill/defer | |
1311 | * every time the priority line is asserted (BT is sending signals on the | |
1312 | * priority line in the PCIx). | |
1313 | * set bt_coex_active to false, uCode will ignore the BT activity and | |
1314 | * perform the normal operation | |
1315 | * | |
1316 | * User might experience transmit issue on some platform due to WiFi/BT | |
1317 | * co-exist problem. The possible behaviors are: | |
1318 | * Able to scan and finding all the available AP | |
1319 | * Not able to associate with any AP | |
1320 | * On those platforms, WiFi communication can be restored by set | |
1321 | * "bt_coex_active" module parameter to "false" | |
1322 | * | |
1323 | * default: bt_coex_active = true (BT_COEX_ENABLE) | |
1324 | */ | |
1325 | module_param_named(bt_coex_active, iwlwifi_mod_params.bt_coex_active, | |
1326 | bool, S_IRUGO); | |
1327 | MODULE_PARM_DESC(bt_coex_active, "enable wifi/bt co-exist (default: enable)"); | |
1328 | ||
1329 | module_param_named(led_mode, iwlwifi_mod_params.led_mode, int, S_IRUGO); | |
1330 | MODULE_PARM_DESC(led_mode, "0=system default, " | |
1331 | "1=On(RF On)/Off(RF Off), 2=blinking, 3=Off (default: 0)"); | |
1332 | ||
1333 | module_param_named(power_save, iwlwifi_mod_params.power_save, | |
1334 | bool, S_IRUGO); | |
1335 | MODULE_PARM_DESC(power_save, | |
1336 | "enable WiFi power management (default: disable)"); | |
1337 | ||
1338 | module_param_named(power_level, iwlwifi_mod_params.power_level, | |
1339 | int, S_IRUGO); | |
1340 | MODULE_PARM_DESC(power_level, | |
1341 | "default power save level (range from 1 - 5, default: 1)"); |