2 * firmware_class.c - Multi purpose firmware loading support
4 * Copyright (c) 2003 Manuel Estrada Sainz
6 * Please see Documentation/firmware_class/ for more information.
10 #include <linux/capability.h>
11 #include <linux/device.h>
12 #include <linux/module.h>
13 #include <linux/init.h>
14 #include <linux/timer.h>
15 #include <linux/vmalloc.h>
16 #include <linux/interrupt.h>
17 #include <linux/bitops.h>
18 #include <linux/mutex.h>
19 #include <linux/workqueue.h>
20 #include <linux/highmem.h>
21 #include <linux/firmware.h>
22 #include <linux/slab.h>
23 #include <linux/sched.h>
25 MODULE_AUTHOR("Manuel Estrada Sainz");
26 MODULE_DESCRIPTION("Multi purpose firmware loading support");
27 MODULE_LICENSE("GPL");
29 /* Builtin firmware support */
31 #ifdef CONFIG_FW_LOADER
33 extern struct builtin_fw __start_builtin_fw[];
34 extern struct builtin_fw __end_builtin_fw[];
36 static bool fw_get_builtin_firmware(struct firmware *fw, const char *name)
38 struct builtin_fw *b_fw;
40 for (b_fw = __start_builtin_fw; b_fw != __end_builtin_fw; b_fw++) {
41 if (strcmp(name, b_fw->name) == 0) {
42 fw->size = b_fw->size;
43 fw->data = b_fw->data;
51 static bool fw_is_builtin_firmware(const struct firmware *fw)
53 struct builtin_fw *b_fw;
55 for (b_fw = __start_builtin_fw; b_fw != __end_builtin_fw; b_fw++)
56 if (fw->data == b_fw->data)
62 #else /* Module case - no builtin firmware support */
64 static inline bool fw_get_builtin_firmware(struct firmware *fw, const char *name)
69 static inline bool fw_is_builtin_firmware(const struct firmware *fw)
81 static int loading_timeout = 60; /* In seconds */
83 static inline long firmware_loading_timeout(void)
85 return loading_timeout > 0 ? loading_timeout * HZ : MAX_SCHEDULE_TIMEOUT;
88 /* fw_lock could be moved to 'struct firmware_priv' but since it is just
89 * guarding for corner cases a global lock should be OK */
90 static DEFINE_MUTEX(fw_lock);
92 struct firmware_priv {
93 struct completion completion;
101 struct timer_list timeout;
107 static struct firmware_priv *to_firmware_priv(struct device *dev)
109 return container_of(dev, struct firmware_priv, dev);
112 static void fw_load_abort(struct firmware_priv *fw_priv)
114 set_bit(FW_STATUS_ABORT, &fw_priv->status);
115 complete(&fw_priv->completion);
118 static ssize_t firmware_timeout_show(struct class *class,
119 struct class_attribute *attr,
122 return sprintf(buf, "%d\n", loading_timeout);
126 * firmware_timeout_store - set number of seconds to wait for firmware
127 * @class: device class pointer
128 * @attr: device attribute pointer
129 * @buf: buffer to scan for timeout value
130 * @count: number of bytes in @buf
132 * Sets the number of seconds to wait for the firmware. Once
133 * this expires an error will be returned to the driver and no
134 * firmware will be provided.
136 * Note: zero means 'wait forever'.
138 static ssize_t firmware_timeout_store(struct class *class,
139 struct class_attribute *attr,
140 const char *buf, size_t count)
142 loading_timeout = simple_strtol(buf, NULL, 10);
143 if (loading_timeout < 0)
149 static struct class_attribute firmware_class_attrs[] = {
150 __ATTR(timeout, S_IWUSR | S_IRUGO,
151 firmware_timeout_show, firmware_timeout_store),
155 static void fw_dev_release(struct device *dev)
157 struct firmware_priv *fw_priv = to_firmware_priv(dev);
160 /* free untransfered pages buffer */
161 for (i = 0; i < fw_priv->nr_pages; i++)
162 __free_page(fw_priv->pages[i]);
163 kfree(fw_priv->pages);
167 module_put(THIS_MODULE);
170 static int firmware_uevent(struct device *dev, struct kobj_uevent_env *env)
172 struct firmware_priv *fw_priv = to_firmware_priv(dev);
174 if (add_uevent_var(env, "FIRMWARE=%s", fw_priv->fw_id))
176 if (add_uevent_var(env, "TIMEOUT=%i", loading_timeout))
178 if (add_uevent_var(env, "ASYNC=%d", fw_priv->nowait))
184 static struct class firmware_class = {
186 .class_attrs = firmware_class_attrs,
187 .dev_uevent = firmware_uevent,
188 .dev_release = fw_dev_release,
191 static ssize_t firmware_loading_show(struct device *dev,
192 struct device_attribute *attr, char *buf)
194 struct firmware_priv *fw_priv = to_firmware_priv(dev);
195 int loading = test_bit(FW_STATUS_LOADING, &fw_priv->status);
197 return sprintf(buf, "%d\n", loading);
200 /* firmware holds the ownership of pages */
201 static void firmware_free_data(const struct firmware *fw)
206 for (i = 0; i < PFN_UP(fw->size); i++)
207 __free_page(fw->pages[i]);
212 /* Some architectures don't have PAGE_KERNEL_RO */
213 #ifndef PAGE_KERNEL_RO
214 #define PAGE_KERNEL_RO PAGE_KERNEL
217 * firmware_loading_store - set value in the 'loading' control file
218 * @dev: device pointer
219 * @attr: device attribute pointer
220 * @buf: buffer to scan for loading control value
221 * @count: number of bytes in @buf
223 * The relevant values are:
225 * 1: Start a load, discarding any previous partial load.
226 * 0: Conclude the load and hand the data to the driver code.
227 * -1: Conclude the load with an error and discard any written data.
229 static ssize_t firmware_loading_store(struct device *dev,
230 struct device_attribute *attr,
231 const char *buf, size_t count)
233 struct firmware_priv *fw_priv = to_firmware_priv(dev);
234 int loading = simple_strtol(buf, NULL, 10);
237 mutex_lock(&fw_lock);
244 /* discarding any previous partial load */
245 if (!test_bit(FW_STATUS_DONE, &fw_priv->status)) {
246 for (i = 0; i < fw_priv->nr_pages; i++)
247 __free_page(fw_priv->pages[i]);
248 kfree(fw_priv->pages);
249 fw_priv->pages = NULL;
250 fw_priv->page_array_size = 0;
251 fw_priv->nr_pages = 0;
252 set_bit(FW_STATUS_LOADING, &fw_priv->status);
256 if (test_bit(FW_STATUS_LOADING, &fw_priv->status)) {
257 set_bit(FW_STATUS_DONE, &fw_priv->status);
258 clear_bit(FW_STATUS_LOADING, &fw_priv->status);
259 complete(&fw_priv->completion);
264 dev_err(dev, "%s: unexpected value (%d)\n", __func__, loading);
267 fw_load_abort(fw_priv);
271 mutex_unlock(&fw_lock);
275 static DEVICE_ATTR(loading, 0644, firmware_loading_show, firmware_loading_store);
277 static ssize_t firmware_data_read(struct file *filp, struct kobject *kobj,
278 struct bin_attribute *bin_attr,
279 char *buffer, loff_t offset, size_t count)
281 struct device *dev = kobj_to_dev(kobj);
282 struct firmware_priv *fw_priv = to_firmware_priv(dev);
286 mutex_lock(&fw_lock);
288 if (!fw || test_bit(FW_STATUS_DONE, &fw_priv->status)) {
292 if (offset > fw_priv->size) {
296 if (count > fw_priv->size - offset)
297 count = fw_priv->size - offset;
303 int page_nr = offset >> PAGE_SHIFT;
304 int page_ofs = offset & (PAGE_SIZE-1);
305 int page_cnt = min_t(size_t, PAGE_SIZE - page_ofs, count);
307 page_data = kmap(fw_priv->pages[page_nr]);
309 memcpy(buffer, page_data + page_ofs, page_cnt);
311 kunmap(fw_priv->pages[page_nr]);
317 mutex_unlock(&fw_lock);
321 static int fw_realloc_buffer(struct firmware_priv *fw_priv, int min_size)
323 int pages_needed = ALIGN(min_size, PAGE_SIZE) >> PAGE_SHIFT;
325 /* If the array of pages is too small, grow it... */
326 if (fw_priv->page_array_size < pages_needed) {
327 int new_array_size = max(pages_needed,
328 fw_priv->page_array_size * 2);
329 struct page **new_pages;
331 new_pages = kmalloc(new_array_size * sizeof(void *),
334 fw_load_abort(fw_priv);
337 memcpy(new_pages, fw_priv->pages,
338 fw_priv->page_array_size * sizeof(void *));
339 memset(&new_pages[fw_priv->page_array_size], 0, sizeof(void *) *
340 (new_array_size - fw_priv->page_array_size));
341 kfree(fw_priv->pages);
342 fw_priv->pages = new_pages;
343 fw_priv->page_array_size = new_array_size;
346 while (fw_priv->nr_pages < pages_needed) {
347 fw_priv->pages[fw_priv->nr_pages] =
348 alloc_page(GFP_KERNEL | __GFP_HIGHMEM);
350 if (!fw_priv->pages[fw_priv->nr_pages]) {
351 fw_load_abort(fw_priv);
360 * firmware_data_write - write method for firmware
361 * @filp: open sysfs file
362 * @kobj: kobject for the device
363 * @bin_attr: bin_attr structure
364 * @buffer: buffer being written
365 * @offset: buffer offset for write in total data store area
366 * @count: buffer size
368 * Data written to the 'data' attribute will be later handed to
369 * the driver as a firmware image.
371 static ssize_t firmware_data_write(struct file *filp, struct kobject *kobj,
372 struct bin_attribute *bin_attr,
373 char *buffer, loff_t offset, size_t count)
375 struct device *dev = kobj_to_dev(kobj);
376 struct firmware_priv *fw_priv = to_firmware_priv(dev);
380 if (!capable(CAP_SYS_RAWIO))
383 mutex_lock(&fw_lock);
385 if (!fw || test_bit(FW_STATUS_DONE, &fw_priv->status)) {
390 retval = fw_realloc_buffer(fw_priv, offset + count);
398 int page_nr = offset >> PAGE_SHIFT;
399 int page_ofs = offset & (PAGE_SIZE - 1);
400 int page_cnt = min_t(size_t, PAGE_SIZE - page_ofs, count);
402 page_data = kmap(fw_priv->pages[page_nr]);
404 memcpy(page_data + page_ofs, buffer, page_cnt);
406 kunmap(fw_priv->pages[page_nr]);
412 fw_priv->size = max_t(size_t, offset, fw_priv->size);
414 mutex_unlock(&fw_lock);
418 static struct bin_attribute firmware_attr_data = {
419 .attr = { .name = "data", .mode = 0644 },
421 .read = firmware_data_read,
422 .write = firmware_data_write,
425 static void firmware_class_timeout(u_long data)
427 struct firmware_priv *fw_priv = (struct firmware_priv *) data;
429 fw_load_abort(fw_priv);
432 static struct firmware_priv *
433 fw_create_instance(struct firmware *firmware, const char *fw_name,
434 struct device *device, bool uevent, bool nowait)
436 struct firmware_priv *fw_priv;
437 struct device *f_dev;
439 fw_priv = kzalloc(sizeof(*fw_priv) + strlen(fw_name) + 1 , GFP_KERNEL);
441 dev_err(device, "%s: kmalloc failed\n", __func__);
442 return ERR_PTR(-ENOMEM);
445 fw_priv->fw = firmware;
446 fw_priv->nowait = nowait;
447 strcpy(fw_priv->fw_id, fw_name);
448 init_completion(&fw_priv->completion);
449 setup_timer(&fw_priv->timeout,
450 firmware_class_timeout, (u_long) fw_priv);
452 f_dev = &fw_priv->dev;
454 device_initialize(f_dev);
455 dev_set_name(f_dev, "%s", dev_name(device));
456 f_dev->parent = device;
457 f_dev->class = &firmware_class;
462 static struct firmware_priv *
463 _request_firmware_prepare(const struct firmware **firmware_p, const char *name,
464 struct device *device, bool uevent, bool nowait)
466 struct firmware *firmware;
467 struct firmware_priv *fw_priv;
470 return ERR_PTR(-EINVAL);
472 *firmware_p = firmware = kzalloc(sizeof(*firmware), GFP_KERNEL);
474 dev_err(device, "%s: kmalloc(struct firmware) failed\n",
476 return ERR_PTR(-ENOMEM);
479 if (fw_get_builtin_firmware(firmware, name)) {
480 dev_dbg(device, "firmware: using built-in firmware %s\n", name);
484 fw_priv = fw_create_instance(firmware, name, device, uevent, nowait);
485 if (IS_ERR(fw_priv)) {
486 release_firmware(firmware);
492 static void _request_firmware_cleanup(const struct firmware **firmware_p)
494 release_firmware(*firmware_p);
498 /* transfer the ownership of pages to firmware */
499 static int fw_set_page_data(struct firmware_priv *fw_priv)
501 struct firmware *fw = fw_priv->fw;
503 fw_priv->data = vmap(fw_priv->pages, fw_priv->nr_pages,
508 fw->data = fw_priv->data;
509 fw->pages = fw_priv->pages;
510 fw->size = fw_priv->size;
512 WARN_ON(PFN_UP(fw->size) != fw_priv->nr_pages);
514 fw_priv->nr_pages = 0;
515 fw_priv->pages = NULL;
516 fw_priv->data = NULL;
521 static int _request_firmware_load(struct firmware_priv *fw_priv, bool uevent,
525 struct device *f_dev = &fw_priv->dev;
527 dev_set_uevent_suppress(f_dev, true);
529 /* Need to pin this module until class device is destroyed */
530 __module_get(THIS_MODULE);
532 retval = device_add(f_dev);
534 dev_err(f_dev, "%s: device_register failed\n", __func__);
538 retval = device_create_bin_file(f_dev, &firmware_attr_data);
540 dev_err(f_dev, "%s: sysfs_create_bin_file failed\n", __func__);
544 retval = device_create_file(f_dev, &dev_attr_loading);
546 dev_err(f_dev, "%s: device_create_file failed\n", __func__);
547 goto err_del_bin_attr;
551 dev_set_uevent_suppress(f_dev, false);
552 dev_dbg(f_dev, "firmware: requesting %s\n", fw_priv->fw_id);
553 if (timeout != MAX_SCHEDULE_TIMEOUT)
554 mod_timer(&fw_priv->timeout,
555 round_jiffies_up(jiffies + timeout));
557 kobject_uevent(&fw_priv->dev.kobj, KOBJ_ADD);
560 wait_for_completion(&fw_priv->completion);
562 del_timer_sync(&fw_priv->timeout);
564 mutex_lock(&fw_lock);
565 if (!fw_priv->size || test_bit(FW_STATUS_ABORT, &fw_priv->status))
568 /* transfer pages ownership at the last minute */
570 retval = fw_set_page_data(fw_priv);
572 mutex_unlock(&fw_lock);
574 device_remove_file(f_dev, &dev_attr_loading);
576 device_remove_bin_file(f_dev, &firmware_attr_data);
585 * request_firmware: - send firmware request and wait for it
586 * @firmware_p: pointer to firmware image
587 * @name: name of firmware file
588 * @device: device for which firmware is being loaded
590 * @firmware_p will be used to return a firmware image by the name
591 * of @name for device @device.
593 * Should be called from user context where sleeping is allowed.
595 * @name will be used as $FIRMWARE in the uevent environment and
596 * should be distinctive enough not to be confused with any other
597 * firmware image for this or any other device.
600 request_firmware(const struct firmware **firmware_p, const char *name,
601 struct device *device)
603 struct firmware_priv *fw_priv;
606 fw_priv = _request_firmware_prepare(firmware_p, name, device, true,
608 if (IS_ERR_OR_NULL(fw_priv))
609 return PTR_RET(fw_priv);
611 ret = usermodehelper_read_trylock();
613 dev_err(device, "firmware: %s will not be loaded\n", name);
615 ret = _request_firmware_load(fw_priv, true,
616 firmware_loading_timeout());
617 usermodehelper_read_unlock();
620 _request_firmware_cleanup(firmware_p);
626 * release_firmware: - release the resource associated with a firmware image
627 * @fw: firmware resource to release
629 void release_firmware(const struct firmware *fw)
632 if (!fw_is_builtin_firmware(fw))
633 firmware_free_data(fw);
639 struct firmware_work {
640 struct work_struct work;
641 struct module *module;
643 struct device *device;
645 void (*cont)(const struct firmware *fw, void *context);
649 static void request_firmware_work_func(struct work_struct *work)
651 struct firmware_work *fw_work;
652 const struct firmware *fw;
653 struct firmware_priv *fw_priv;
657 fw_work = container_of(work, struct firmware_work, work);
658 fw_priv = _request_firmware_prepare(&fw, fw_work->name, fw_work->device,
659 fw_work->uevent, true);
660 if (IS_ERR_OR_NULL(fw_priv)) {
661 ret = PTR_RET(fw_priv);
665 timeout = usermodehelper_read_lock_wait(firmware_loading_timeout());
667 ret = _request_firmware_load(fw_priv, fw_work->uevent, timeout);
668 usermodehelper_read_unlock();
670 dev_dbg(fw_work->device, "firmware: %s loading timed out\n",
675 _request_firmware_cleanup(&fw);
678 fw_work->cont(fw, fw_work->context);
680 module_put(fw_work->module);
685 * request_firmware_nowait - asynchronous version of request_firmware
686 * @module: module requesting the firmware
687 * @uevent: sends uevent to copy the firmware image if this flag
688 * is non-zero else the firmware copy must be done manually.
689 * @name: name of firmware file
690 * @device: device for which firmware is being loaded
691 * @gfp: allocation flags
692 * @context: will be passed over to @cont, and
693 * @fw may be %NULL if firmware request fails.
694 * @cont: function will be called asynchronously when the firmware
697 * Asynchronous variant of request_firmware() for user contexts where
698 * it is not possible to sleep for long time. It can't be called
699 * in atomic contexts.
702 request_firmware_nowait(
703 struct module *module, bool uevent,
704 const char *name, struct device *device, gfp_t gfp, void *context,
705 void (*cont)(const struct firmware *fw, void *context))
707 struct firmware_work *fw_work;
709 fw_work = kzalloc(sizeof (struct firmware_work), gfp);
713 fw_work->module = module;
714 fw_work->name = name;
715 fw_work->device = device;
716 fw_work->context = context;
717 fw_work->cont = cont;
718 fw_work->uevent = uevent;
720 if (!try_module_get(module)) {
725 INIT_WORK(&fw_work->work, request_firmware_work_func);
726 schedule_work(&fw_work->work);
730 static int __init firmware_class_init(void)
732 return class_register(&firmware_class);
735 static void __exit firmware_class_exit(void)
737 class_unregister(&firmware_class);
740 fs_initcall(firmware_class_init);
741 module_exit(firmware_class_exit);
743 EXPORT_SYMBOL(release_firmware);
744 EXPORT_SYMBOL(request_firmware);
745 EXPORT_SYMBOL(request_firmware_nowait);