Commit | Line | Data |
---|---|---|
50f86aed | 1 | # SPDX-License-Identifier: GPL-2.0 |
06bfd3c8 LR |
2 | menu "Firmware loader" |
3 | ||
4 | config FW_LOADER | |
5 | tristate "Firmware loading facility" if EXPERT | |
6 | default y | |
7 | help | |
8 | This enables the firmware loading facility in the kernel. The kernel | |
9 | will first look for built-in firmware, if it has any. Next, it will | |
10 | look for the requested firmware in a series of filesystem paths: | |
11 | ||
12 | o firmware_class path module parameter or kernel boot param | |
13 | o /lib/firmware/updates/UTS_RELEASE | |
14 | o /lib/firmware/updates | |
15 | o /lib/firmware/UTS_RELEASE | |
16 | o /lib/firmware | |
17 | ||
18 | Enabling this feature only increases your kernel image by about | |
19 | 828 bytes, enable this option unless you are certain you don't | |
20 | need firmware. | |
21 | ||
22 | You typically want this built-in (=y) but you can also enable this | |
23 | as a module, in which case the firmware_class module will be built. | |
24 | You also want to be sure to enable this built-in if you are going to | |
25 | enable built-in firmware (CONFIG_EXTRA_FIRMWARE). | |
26 | ||
27 | if FW_LOADER | |
28 | ||
82fd7a81 TI |
29 | config FW_LOADER_PAGED_BUF |
30 | bool | |
31 | ||
06bfd3c8 LR |
32 | config EXTRA_FIRMWARE |
33 | string "Build named firmware blobs into the kernel binary" | |
34 | help | |
35 | Device drivers which require firmware can typically deal with | |
36 | having the kernel load firmware from the various supported | |
37 | /lib/firmware/ paths. This option enables you to build into the | |
38 | kernel firmware files. Built-in firmware searches are preceded | |
39 | over firmware lookups using your filesystem over the supported | |
40 | /lib/firmware paths documented on CONFIG_FW_LOADER. | |
41 | ||
42 | This may be useful for testing or if the firmware is required early on | |
43 | in boot and cannot rely on the firmware being placed in an initrd or | |
44 | initramfs. | |
45 | ||
46 | This option is a string and takes the (space-separated) names of the | |
47 | firmware files -- the same names that appear in MODULE_FIRMWARE() | |
48 | and request_firmware() in the source. These files should exist under | |
49 | the directory specified by the EXTRA_FIRMWARE_DIR option, which is | |
50 | /lib/firmware by default. | |
51 | ||
52 | For example, you might set CONFIG_EXTRA_FIRMWARE="usb8388.bin", copy | |
53 | the usb8388.bin file into /lib/firmware, and build the kernel. Then | |
54 | any request_firmware("usb8388.bin") will be satisfied internally | |
55 | inside the kernel without ever looking at your filesystem at runtime. | |
56 | ||
57 | WARNING: If you include additional firmware files into your binary | |
58 | kernel image that are not available under the terms of the GPL, | |
59 | then it may be a violation of the GPL to distribute the resulting | |
60 | image since it combines both GPL and non-GPL work. You should | |
61 | consult a lawyer of your own before distributing such an image. | |
62 | ||
63 | config EXTRA_FIRMWARE_DIR | |
64 | string "Firmware blobs root directory" | |
65 | depends on EXTRA_FIRMWARE != "" | |
66 | default "/lib/firmware" | |
67 | help | |
68 | This option controls the directory in which the kernel build system | |
69 | looks for the firmware files listed in the EXTRA_FIRMWARE option. | |
70 | ||
71 | config FW_LOADER_USER_HELPER | |
72 | bool "Enable the firmware sysfs fallback mechanism" | |
82fd7a81 | 73 | select FW_LOADER_PAGED_BUF |
06bfd3c8 LR |
74 | help |
75 | This option enables a sysfs loading facility to enable firmware | |
76 | loading to the kernel through userspace as a fallback mechanism | |
77 | if and only if the kernel's direct filesystem lookup for the | |
78 | firmware failed using the different /lib/firmware/ paths, or the | |
79 | path specified in the firmware_class path module parameter, or the | |
80 | firmware_class path kernel boot parameter if the firmware_class is | |
81 | built-in. For details on how to work with the sysfs fallback mechanism | |
82 | refer to Documentation/driver-api/firmware/fallback-mechanisms.rst. | |
83 | ||
84 | The direct filesystem lookup for firmware is always used first now. | |
85 | ||
86 | If the kernel's direct filesystem lookup for firmware fails to find | |
87 | the requested firmware a sysfs fallback loading facility is made | |
88 | available and userspace is informed about this through uevents. | |
89 | The uevent can be suppressed if the driver explicitly requested it, | |
90 | this is known as the driver using the custom fallback mechanism. | |
91 | If the custom fallback mechanism is used userspace must always | |
92 | acknowledge failure to find firmware as the timeout for the fallback | |
93 | mechanism is disabled, and failed requests will linger forever. | |
94 | ||
95 | This used to be the default firmware loading facility, and udev used | |
96 | to listen for uvents to load firmware for the kernel. The firmware | |
97 | loading facility functionality in udev has been removed, as such it | |
98 | can no longer be relied upon as a fallback mechanism. Linux no longer | |
99 | relies on or uses a fallback mechanism in userspace. If you need to | |
100 | rely on one refer to the permissively licensed firmwared: | |
101 | ||
102 | https://github.com/teg/firmwared | |
103 | ||
104 | Since this was the default firmware loading facility at one point, | |
105 | old userspace may exist which relies upon it, and as such this | |
106 | mechanism can never be removed from the kernel. | |
107 | ||
108 | You should only enable this functionality if you are certain you | |
109 | require a fallback mechanism and have a userspace mechanism ready to | |
110 | load firmware in case it is not found. One main reason for this may | |
111 | be if you have drivers which require firmware built-in and for | |
112 | whatever reason cannot place the required firmware in initramfs. | |
113 | Another reason kernels may have this feature enabled is to support a | |
114 | driver which explicitly relies on this fallback mechanism. Only two | |
115 | drivers need this today: | |
116 | ||
117 | o CONFIG_LEDS_LP55XX_COMMON | |
118 | o CONFIG_DELL_RBU | |
119 | ||
120 | Outside of supporting the above drivers, another reason for needing | |
121 | this may be that your firmware resides outside of the paths the kernel | |
122 | looks for and cannot possibly be specified using the firmware_class | |
123 | path module parameter or kernel firmware_class path boot parameter | |
124 | if firmware_class is built-in. | |
125 | ||
126 | A modern use case may be to temporarily mount a custom partition | |
127 | during provisioning which is only accessible to userspace, and then | |
128 | to use it to look for and fetch the required firmware. Such type of | |
129 | driver functionality may not even ever be desirable upstream by | |
130 | vendors, and as such is only required to be supported as an interface | |
131 | for provisioning. Since udev's firmware loading facility has been | |
132 | removed you can use firmwared or a fork of it to customize how you | |
133 | want to load firmware based on uevents issued. | |
134 | ||
135 | Enabling this option will increase your kernel image size by about | |
136 | 13436 bytes. | |
137 | ||
138 | If you are unsure about this, say N here, unless you are Linux | |
139 | distribution and need to support the above two drivers, or you are | |
140 | certain you need to support some really custom firmware loading | |
141 | facility in userspace. | |
142 | ||
143 | config FW_LOADER_USER_HELPER_FALLBACK | |
144 | bool "Force the firmware sysfs fallback mechanism when possible" | |
145 | depends on FW_LOADER_USER_HELPER | |
146 | help | |
147 | Enabling this option forces a sysfs userspace fallback mechanism | |
148 | to be used for all firmware requests which explicitly do not disable a | |
149 | a fallback mechanism. Firmware calls which do prohibit a fallback | |
150 | mechanism is request_firmware_direct(). This option is kept for | |
151 | backward compatibility purposes given this precise mechanism can also | |
152 | be enabled by setting the proc sysctl value to true: | |
153 | ||
154 | /proc/sys/kernel/firmware_config/force_sysfs_fallback | |
155 | ||
156 | If you are unsure about this, say N here. | |
157 | ||
82fd7a81 TI |
158 | config FW_LOADER_COMPRESS |
159 | bool "Enable compressed firmware support" | |
160 | select FW_LOADER_PAGED_BUF | |
161 | select XZ_DEC | |
162 | help | |
163 | This option enables the support for loading compressed firmware | |
164 | files. The caller of firmware API receives the decompressed file | |
165 | content. The compressed file is loaded as a fallback, only after | |
166 | loading the raw file failed at first. | |
167 | ||
168 | Currently only XZ-compressed files are supported, and they have to | |
169 | be compressed with either none or crc32 integrity check type (pass | |
170 | "-C crc32" option to xz command). | |
171 | ||
06bfd3c8 LR |
172 | endif # FW_LOADER |
173 | endmenu |