blob: 815b711bcd85007569918048b2d3e36fe20fea19 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
2 request_firmware() hotplug interface:
3 ------------------------------------
Markus Rechberger87d37a42007-06-04 18:45:44 +02004 Copyright (C) 2003 Manuel Estrada Sainz
Linus Torvalds1da177e2005-04-16 15:20:36 -07005
6 Why:
7 ---
8
9 Today, the most extended way to use firmware in the Linux kernel is linking
10 it statically in a header file. Which has political and technical issues:
11
12 1) Some firmware is not legal to redistribute.
13 2) The firmware occupies memory permanently, even though it often is just
14 used once.
15 3) Some people, like the Debian crowd, don't consider some firmware free
16 enough and remove entire drivers (e.g.: keyspan).
17
18 High level behavior (mixed):
19 ============================
20
Ming Lei10bd4c72012-10-24 10:49:33 +080021 1), kernel(driver):
22 - calls request_firmware(&fw_entry, $FIRMWARE, device)
23 - kernel searchs the fimware image with name $FIRMWARE directly
24 in the below search path of root filesystem:
25 "/lib/firmware/updates/" UTS_RELEASE,
26 "/lib/firmware/updates",
27 "/lib/firmware/" UTS_RELEASE,
28 "/lib/firmware"
29 - If found, goto 7), else goto 2)
Linus Torvalds1da177e2005-04-16 15:20:36 -070030
Ming Lei10bd4c72012-10-24 10:49:33 +080031 2), userspace:
Linus Torvalds1da177e2005-04-16 15:20:36 -070032 - /sys/class/firmware/xxx/{loading,data} appear.
33 - hotplug gets called with a firmware identifier in $FIRMWARE
34 and the usual hotplug environment.
35 - hotplug: echo 1 > /sys/class/firmware/xxx/loading
36
Ming Lei10bd4c72012-10-24 10:49:33 +080037 3), kernel: Discard any previous partial load.
Linus Torvalds1da177e2005-04-16 15:20:36 -070038
Ming Lei10bd4c72012-10-24 10:49:33 +080039 4), userspace:
Linus Torvalds1da177e2005-04-16 15:20:36 -070040 - hotplug: cat appropriate_firmware_image > \
41 /sys/class/firmware/xxx/data
42
Ming Lei10bd4c72012-10-24 10:49:33 +080043 5), kernel: grows a buffer in PAGE_SIZE increments to hold the image as it
Linus Torvalds1da177e2005-04-16 15:20:36 -070044 comes in.
45
Ming Lei10bd4c72012-10-24 10:49:33 +080046 6), userspace:
Linus Torvalds1da177e2005-04-16 15:20:36 -070047 - hotplug: echo 0 > /sys/class/firmware/xxx/loading
48
Ming Lei10bd4c72012-10-24 10:49:33 +080049 7), kernel: request_firmware() returns and the driver has the firmware
Linus Torvalds1da177e2005-04-16 15:20:36 -070050 image in fw_entry->{data,size}. If something went wrong
51 request_firmware() returns non-zero and fw_entry is set to
52 NULL.
53
Ming Lei10bd4c72012-10-24 10:49:33 +080054 8), kernel(driver): Driver code calls release_firmware(fw_entry) releasing
Linus Torvalds1da177e2005-04-16 15:20:36 -070055 the firmware image and any related resource.
56
57 High level behavior (driver code):
58 ==================================
59
60 if(request_firmware(&fw_entry, $FIRMWARE, device) == 0)
61 copy_fw_to_device(fw_entry->data, fw_entry->size);
62 release(fw_entry);
63
64 Sample/simple hotplug script:
65 ============================
66
67 # Both $DEVPATH and $FIRMWARE are already provided in the environment.
68
69 HOTPLUG_FW_DIR=/usr/lib/hotplug/firmware/
70
71 echo 1 > /sys/$DEVPATH/loading
72 cat $HOTPLUG_FW_DIR/$FIRMWARE > /sysfs/$DEVPATH/data
73 echo 0 > /sys/$DEVPATH/loading
74
75 Random notes:
76 ============
77
78 - "echo -1 > /sys/class/firmware/xxx/loading" will cancel the load at
79 once and make request_firmware() return with error.
80
81 - firmware_data_read() and firmware_loading_show() are just provided
82 for testing and completeness, they are not called in normal use.
83
84 - There is also /sys/class/firmware/timeout which holds a timeout in
85 seconds for the whole load operation.
86
87 - request_firmware_nowait() is also provided for convenience in
Ming Lei7fcab092009-05-29 11:33:19 +080088 user contexts to request firmware asynchronously, but can't be called
89 in atomic contexts.
Linus Torvalds1da177e2005-04-16 15:20:36 -070090
91
92 about in-kernel persistence:
93 ---------------------------
94 Under some circumstances, as explained below, it would be interesting to keep
95 firmware images in non-swappable kernel memory or even in the kernel image
96 (probably within initramfs).
97
98 Note that this functionality has not been implemented.
99
100 - Why OPTIONAL in-kernel persistence may be a good idea sometimes:
101
102 - If the device that needs the firmware is needed to access the
103 filesystem. When upon some error the device has to be reset and the
104 firmware reloaded, it won't be possible to get it from userspace.
105 e.g.:
106 - A diskless client with a network card that needs firmware.
107 - The filesystem is stored in a disk behind an scsi device
108 that needs firmware.
109 - Replacing buggy DSDT/SSDT ACPI tables on boot.
110 Note: this would require the persistent objects to be included
111 within the kernel image, probably within initramfs.
112
113 And the same device can be needed to access the filesystem or not depending
114 on the setup, so I think that the choice on what firmware to make
115 persistent should be left to userspace.
116