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>
24 #include <linux/file.h>
25 #include <linux/list.h>
26 #include <linux/async.h>
28 #include <linux/suspend.h>
29 #include <linux/syscore_ops.h>
31 #include <generated/utsrelease.h>
35 #define to_dev(obj) container_of(obj, struct device, kobj)
37 MODULE_AUTHOR("Manuel Estrada Sainz");
38 MODULE_DESCRIPTION("Multi purpose firmware loading support");
39 MODULE_LICENSE("GPL");
41 static const char *fw_path[] = {
42 "/lib/firmware/updates/" UTS_RELEASE,
43 "/lib/firmware/updates",
44 "/lib/firmware/" UTS_RELEASE,
48 /* Don't inline this: 'struct kstat' is biggish */
49 static noinline long fw_file_size(struct file *file)
52 if (vfs_getattr(file->f_path.mnt, file->f_path.dentry, &st))
54 if (!S_ISREG(st.mode))
56 if (st.size != (long)st.size)
61 static bool fw_read_file_contents(struct file *file, struct firmware *fw)
67 size = fw_file_size(file);
74 if (vfs_read(file, buf, size, &pos) != size) {
83 static bool fw_get_filesystem_firmware(struct firmware *fw, const char *name)
87 char *path = __getname();
89 for (i = 0; i < ARRAY_SIZE(fw_path); i++) {
91 snprintf(path, PATH_MAX, "%s/%s", fw_path[i], name);
93 file = filp_open(path, O_RDONLY, 0);
96 success = fw_read_file_contents(file, fw);
105 /* Builtin firmware support */
107 #ifdef CONFIG_FW_LOADER
109 extern struct builtin_fw __start_builtin_fw[];
110 extern struct builtin_fw __end_builtin_fw[];
112 static bool fw_get_builtin_firmware(struct firmware *fw, const char *name)
114 struct builtin_fw *b_fw;
116 for (b_fw = __start_builtin_fw; b_fw != __end_builtin_fw; b_fw++) {
117 if (strcmp(name, b_fw->name) == 0) {
118 fw->size = b_fw->size;
119 fw->data = b_fw->data;
127 static bool fw_is_builtin_firmware(const struct firmware *fw)
129 struct builtin_fw *b_fw;
131 for (b_fw = __start_builtin_fw; b_fw != __end_builtin_fw; b_fw++)
132 if (fw->data == b_fw->data)
138 #else /* Module case - no builtin firmware support */
140 static inline bool fw_get_builtin_firmware(struct firmware *fw, const char *name)
145 static inline bool fw_is_builtin_firmware(const struct firmware *fw)
157 static int loading_timeout = 60; /* In seconds */
159 static inline long firmware_loading_timeout(void)
161 return loading_timeout > 0 ? loading_timeout * HZ : MAX_SCHEDULE_TIMEOUT;
164 /* fw_lock could be moved to 'struct firmware_priv' but since it is just
165 * guarding for corner cases a global lock should be OK */
166 static DEFINE_MUTEX(fw_lock);
168 struct firmware_priv {
169 struct completion completion;
171 unsigned long status;
175 struct timer_list timeout;
181 static struct firmware_priv *to_firmware_priv(struct device *dev)
183 return container_of(dev, struct firmware_priv, dev);
186 static void fw_load_abort(struct firmware_priv *fw_priv)
188 set_bit(FW_STATUS_ABORT, &fw_priv->status);
190 complete(&fw_priv->completion);
193 static ssize_t firmware_timeout_show(struct class *class,
194 struct class_attribute *attr,
197 return sprintf(buf, "%d\n", loading_timeout);
201 * firmware_timeout_store - set number of seconds to wait for firmware
202 * @class: device class pointer
203 * @attr: device attribute pointer
204 * @buf: buffer to scan for timeout value
205 * @count: number of bytes in @buf
207 * Sets the number of seconds to wait for the firmware. Once
208 * this expires an error will be returned to the driver and no
209 * firmware will be provided.
211 * Note: zero means 'wait forever'.
213 static ssize_t firmware_timeout_store(struct class *class,
214 struct class_attribute *attr,
215 const char *buf, size_t count)
217 loading_timeout = simple_strtol(buf, NULL, 10);
218 if (loading_timeout < 0)
224 static struct class_attribute firmware_class_attrs[] = {
225 __ATTR(timeout, S_IWUSR | S_IRUGO,
226 firmware_timeout_show, firmware_timeout_store),
230 static void fw_dev_release(struct device *dev)
232 struct firmware_priv *fw_priv = to_firmware_priv(dev);
235 for (i = 0; i < fw_priv->nr_pages; i++)
236 __free_page(fw_priv->pages[i]);
237 kfree(fw_priv->pages);
240 module_put(THIS_MODULE);
243 static int firmware_uevent(struct device *dev, struct kobj_uevent_env *env)
245 struct firmware_priv *fw_priv = to_firmware_priv(dev);
247 if (add_uevent_var(env, "FIRMWARE=%s", fw_priv->fw_id))
249 if (add_uevent_var(env, "TIMEOUT=%i", loading_timeout))
251 if (add_uevent_var(env, "ASYNC=%d", fw_priv->nowait))
257 static struct class firmware_class = {
259 .class_attrs = firmware_class_attrs,
260 .dev_uevent = firmware_uevent,
261 .dev_release = fw_dev_release,
264 static ssize_t firmware_loading_show(struct device *dev,
265 struct device_attribute *attr, char *buf)
267 struct firmware_priv *fw_priv = to_firmware_priv(dev);
268 int loading = test_bit(FW_STATUS_LOADING, &fw_priv->status);
270 return sprintf(buf, "%d\n", loading);
273 static void firmware_free_data(const struct firmware *fw)
276 /* Loaded directly? */
283 for (i = 0; i < PFN_UP(fw->size); i++)
284 __free_page(fw->pages[i]);
289 /* Some architectures don't have PAGE_KERNEL_RO */
290 #ifndef PAGE_KERNEL_RO
291 #define PAGE_KERNEL_RO PAGE_KERNEL
294 * firmware_loading_store - set value in the 'loading' control file
295 * @dev: device pointer
296 * @attr: device attribute pointer
297 * @buf: buffer to scan for loading control value
298 * @count: number of bytes in @buf
300 * The relevant values are:
302 * 1: Start a load, discarding any previous partial load.
303 * 0: Conclude the load and hand the data to the driver code.
304 * -1: Conclude the load with an error and discard any written data.
306 static ssize_t firmware_loading_store(struct device *dev,
307 struct device_attribute *attr,
308 const char *buf, size_t count)
310 struct firmware_priv *fw_priv = to_firmware_priv(dev);
311 int loading = simple_strtol(buf, NULL, 10);
314 mutex_lock(&fw_lock);
321 firmware_free_data(fw_priv->fw);
322 memset(fw_priv->fw, 0, sizeof(struct firmware));
323 /* If the pages are not owned by 'struct firmware' */
324 for (i = 0; i < fw_priv->nr_pages; i++)
325 __free_page(fw_priv->pages[i]);
326 kfree(fw_priv->pages);
327 fw_priv->pages = NULL;
328 fw_priv->page_array_size = 0;
329 fw_priv->nr_pages = 0;
330 set_bit(FW_STATUS_LOADING, &fw_priv->status);
333 if (test_bit(FW_STATUS_LOADING, &fw_priv->status)) {
334 vunmap(fw_priv->fw->data);
335 fw_priv->fw->data = vmap(fw_priv->pages,
338 if (!fw_priv->fw->data) {
339 dev_err(dev, "%s: vmap() failed\n", __func__);
342 /* Pages are now owned by 'struct firmware' */
343 fw_priv->fw->pages = fw_priv->pages;
344 fw_priv->pages = NULL;
346 fw_priv->page_array_size = 0;
347 fw_priv->nr_pages = 0;
348 complete(&fw_priv->completion);
349 clear_bit(FW_STATUS_LOADING, &fw_priv->status);
354 dev_err(dev, "%s: unexpected value (%d)\n", __func__, loading);
358 fw_load_abort(fw_priv);
362 mutex_unlock(&fw_lock);
366 static DEVICE_ATTR(loading, 0644, firmware_loading_show, firmware_loading_store);
368 static ssize_t firmware_data_read(struct file *filp, struct kobject *kobj,
369 struct bin_attribute *bin_attr,
370 char *buffer, loff_t offset, size_t count)
372 struct device *dev = to_dev(kobj);
373 struct firmware_priv *fw_priv = to_firmware_priv(dev);
377 mutex_lock(&fw_lock);
379 if (!fw || test_bit(FW_STATUS_DONE, &fw_priv->status)) {
383 if (offset > fw->size) {
387 if (count > fw->size - offset)
388 count = fw->size - offset;
394 int page_nr = offset >> PAGE_SHIFT;
395 int page_ofs = offset & (PAGE_SIZE-1);
396 int page_cnt = min_t(size_t, PAGE_SIZE - page_ofs, count);
398 page_data = kmap(fw_priv->pages[page_nr]);
400 memcpy(buffer, page_data + page_ofs, page_cnt);
402 kunmap(fw_priv->pages[page_nr]);
408 mutex_unlock(&fw_lock);
412 static int fw_realloc_buffer(struct firmware_priv *fw_priv, int min_size)
414 int pages_needed = ALIGN(min_size, PAGE_SIZE) >> PAGE_SHIFT;
416 /* If the array of pages is too small, grow it... */
417 if (fw_priv->page_array_size < pages_needed) {
418 int new_array_size = max(pages_needed,
419 fw_priv->page_array_size * 2);
420 struct page **new_pages;
422 new_pages = kmalloc(new_array_size * sizeof(void *),
425 fw_load_abort(fw_priv);
428 memcpy(new_pages, fw_priv->pages,
429 fw_priv->page_array_size * sizeof(void *));
430 memset(&new_pages[fw_priv->page_array_size], 0, sizeof(void *) *
431 (new_array_size - fw_priv->page_array_size));
432 kfree(fw_priv->pages);
433 fw_priv->pages = new_pages;
434 fw_priv->page_array_size = new_array_size;
437 while (fw_priv->nr_pages < pages_needed) {
438 fw_priv->pages[fw_priv->nr_pages] =
439 alloc_page(GFP_KERNEL | __GFP_HIGHMEM);
441 if (!fw_priv->pages[fw_priv->nr_pages]) {
442 fw_load_abort(fw_priv);
451 * firmware_data_write - write method for firmware
452 * @filp: open sysfs file
453 * @kobj: kobject for the device
454 * @bin_attr: bin_attr structure
455 * @buffer: buffer being written
456 * @offset: buffer offset for write in total data store area
457 * @count: buffer size
459 * Data written to the 'data' attribute will be later handed to
460 * the driver as a firmware image.
462 static ssize_t firmware_data_write(struct file *filp, struct kobject *kobj,
463 struct bin_attribute *bin_attr,
464 char *buffer, loff_t offset, size_t count)
466 struct device *dev = to_dev(kobj);
467 struct firmware_priv *fw_priv = to_firmware_priv(dev);
471 if (!capable(CAP_SYS_RAWIO))
474 mutex_lock(&fw_lock);
476 if (!fw || test_bit(FW_STATUS_DONE, &fw_priv->status)) {
480 retval = fw_realloc_buffer(fw_priv, offset + count);
488 int page_nr = offset >> PAGE_SHIFT;
489 int page_ofs = offset & (PAGE_SIZE - 1);
490 int page_cnt = min_t(size_t, PAGE_SIZE - page_ofs, count);
492 page_data = kmap(fw_priv->pages[page_nr]);
494 memcpy(page_data + page_ofs, buffer, page_cnt);
496 kunmap(fw_priv->pages[page_nr]);
502 fw->size = max_t(size_t, offset, fw->size);
504 mutex_unlock(&fw_lock);
508 static struct bin_attribute firmware_attr_data = {
509 .attr = { .name = "data", .mode = 0644 },
511 .read = firmware_data_read,
512 .write = firmware_data_write,
515 static void firmware_class_timeout(u_long data)
517 struct firmware_priv *fw_priv = (struct firmware_priv *) data;
519 fw_load_abort(fw_priv);
522 static struct firmware_priv *
523 fw_create_instance(struct firmware *firmware, const char *fw_name,
524 struct device *device, bool uevent, bool nowait)
526 struct firmware_priv *fw_priv;
527 struct device *f_dev;
529 fw_priv = kzalloc(sizeof(*fw_priv) + strlen(fw_name) + 1 , GFP_KERNEL);
531 dev_err(device, "%s: kmalloc failed\n", __func__);
532 return ERR_PTR(-ENOMEM);
535 fw_priv->fw = firmware;
536 fw_priv->nowait = nowait;
537 strcpy(fw_priv->fw_id, fw_name);
538 init_completion(&fw_priv->completion);
539 setup_timer(&fw_priv->timeout,
540 firmware_class_timeout, (u_long) fw_priv);
542 f_dev = &fw_priv->dev;
544 device_initialize(f_dev);
545 dev_set_name(f_dev, "%s", dev_name(device));
546 f_dev->parent = device;
547 f_dev->class = &firmware_class;
552 static struct firmware_priv *
553 _request_firmware_prepare(const struct firmware **firmware_p, const char *name,
554 struct device *device, bool uevent, bool nowait)
556 struct firmware *firmware;
557 struct firmware_priv *fw_priv;
560 return ERR_PTR(-EINVAL);
562 *firmware_p = firmware = kzalloc(sizeof(*firmware), GFP_KERNEL);
564 dev_err(device, "%s: kmalloc(struct firmware) failed\n",
566 return ERR_PTR(-ENOMEM);
569 if (fw_get_builtin_firmware(firmware, name)) {
570 dev_dbg(device, "firmware: using built-in firmware %s\n", name);
574 if (fw_get_filesystem_firmware(firmware, name)) {
575 dev_dbg(device, "firmware: direct-loading firmware %s\n", name);
579 fw_priv = fw_create_instance(firmware, name, device, uevent, nowait);
580 if (IS_ERR(fw_priv)) {
581 release_firmware(firmware);
587 static void _request_firmware_cleanup(const struct firmware **firmware_p)
589 release_firmware(*firmware_p);
593 static int _request_firmware_load(struct firmware_priv *fw_priv, bool uevent,
597 struct device *f_dev = &fw_priv->dev;
599 dev_set_uevent_suppress(f_dev, true);
601 /* Need to pin this module until class device is destroyed */
602 __module_get(THIS_MODULE);
604 retval = device_add(f_dev);
606 dev_err(f_dev, "%s: device_register failed\n", __func__);
610 retval = device_create_bin_file(f_dev, &firmware_attr_data);
612 dev_err(f_dev, "%s: sysfs_create_bin_file failed\n", __func__);
616 retval = device_create_file(f_dev, &dev_attr_loading);
618 dev_err(f_dev, "%s: device_create_file failed\n", __func__);
619 goto err_del_bin_attr;
623 dev_set_uevent_suppress(f_dev, false);
624 dev_dbg(f_dev, "firmware: requesting %s\n", fw_priv->fw_id);
625 if (timeout != MAX_SCHEDULE_TIMEOUT)
626 mod_timer(&fw_priv->timeout,
627 round_jiffies_up(jiffies + timeout));
629 kobject_uevent(&fw_priv->dev.kobj, KOBJ_ADD);
632 wait_for_completion(&fw_priv->completion);
634 set_bit(FW_STATUS_DONE, &fw_priv->status);
635 del_timer_sync(&fw_priv->timeout);
637 mutex_lock(&fw_lock);
638 if (!fw_priv->fw->size || test_bit(FW_STATUS_ABORT, &fw_priv->status))
641 mutex_unlock(&fw_lock);
643 device_remove_file(f_dev, &dev_attr_loading);
645 device_remove_bin_file(f_dev, &firmware_attr_data);
654 * request_firmware: - send firmware request and wait for it
655 * @firmware_p: pointer to firmware image
656 * @name: name of firmware file
657 * @device: device for which firmware is being loaded
659 * @firmware_p will be used to return a firmware image by the name
660 * of @name for device @device.
662 * Should be called from user context where sleeping is allowed.
664 * @name will be used as $FIRMWARE in the uevent environment and
665 * should be distinctive enough not to be confused with any other
666 * firmware image for this or any other device.
669 request_firmware(const struct firmware **firmware_p, const char *name,
670 struct device *device)
672 struct firmware_priv *fw_priv;
675 fw_priv = _request_firmware_prepare(firmware_p, name, device, true,
677 if (IS_ERR_OR_NULL(fw_priv))
678 return PTR_RET(fw_priv);
680 ret = usermodehelper_read_trylock();
683 dev_err(device, "firmware: %s will not be loaded\n", name);
685 ret = _request_firmware_load(fw_priv, true,
686 firmware_loading_timeout());
687 usermodehelper_read_unlock();
690 _request_firmware_cleanup(firmware_p);
696 * release_firmware: - release the resource associated with a firmware image
697 * @fw: firmware resource to release
699 void release_firmware(const struct firmware *fw)
702 if (!fw_is_builtin_firmware(fw))
703 firmware_free_data(fw);
709 struct firmware_work {
710 struct work_struct work;
711 struct module *module;
713 struct device *device;
715 void (*cont)(const struct firmware *fw, void *context);
719 static void request_firmware_work_func(struct work_struct *work)
721 struct firmware_work *fw_work;
722 const struct firmware *fw;
723 struct firmware_priv *fw_priv;
727 fw_work = container_of(work, struct firmware_work, work);
728 fw_priv = _request_firmware_prepare(&fw, fw_work->name, fw_work->device,
729 fw_work->uevent, true);
730 if (IS_ERR_OR_NULL(fw_priv)) {
731 ret = PTR_RET(fw_priv);
735 timeout = usermodehelper_read_lock_wait(firmware_loading_timeout());
737 ret = _request_firmware_load(fw_priv, fw_work->uevent, timeout);
738 usermodehelper_read_unlock();
740 dev_dbg(fw_work->device, "firmware: %s loading timed out\n",
745 _request_firmware_cleanup(&fw);
748 fw_work->cont(fw, fw_work->context);
750 module_put(fw_work->module);
755 * request_firmware_nowait - asynchronous version of request_firmware
756 * @module: module requesting the firmware
757 * @uevent: sends uevent to copy the firmware image if this flag
758 * is non-zero else the firmware copy must be done manually.
759 * @name: name of firmware file
760 * @device: device for which firmware is being loaded
761 * @gfp: allocation flags
762 * @context: will be passed over to @cont, and
763 * @fw may be %NULL if firmware request fails.
764 * @cont: function will be called asynchronously when the firmware
767 * Asynchronous variant of request_firmware() for user contexts where
768 * it is not possible to sleep for long time. It can't be called
769 * in atomic contexts.
772 request_firmware_nowait(
773 struct module *module, bool uevent,
774 const char *name, struct device *device, gfp_t gfp, void *context,
775 void (*cont)(const struct firmware *fw, void *context))
777 struct firmware_work *fw_work;
779 fw_work = kzalloc(sizeof (struct firmware_work), gfp);
783 fw_work->module = module;
784 fw_work->name = name;
785 fw_work->device = device;
786 fw_work->context = context;
787 fw_work->cont = cont;
788 fw_work->uevent = uevent;
790 if (!try_module_get(module)) {
795 INIT_WORK(&fw_work->work, request_firmware_work_func);
796 schedule_work(&fw_work->work);
800 static int __init firmware_class_init(void)
802 return class_register(&firmware_class);
805 static void __exit firmware_class_exit(void)
807 class_unregister(&firmware_class);
810 fs_initcall(firmware_class_init);
811 module_exit(firmware_class_exit);
813 EXPORT_SYMBOL(release_firmware);
814 EXPORT_SYMBOL(request_firmware);
815 EXPORT_SYMBOL(request_firmware_nowait);