0001 # SPDX-License-Identifier: GPL-2.0
0002 menu "Firmware loader"
0003
0004 config FW_LOADER
0005 tristate "Firmware loading facility" if EXPERT
0006 default y
0007 help
0008 This enables the firmware loading facility in the kernel. The kernel
0009 will first look for built-in firmware, if it has any. Next, it will
0010 look for the requested firmware in a series of filesystem paths:
0011
0012 o firmware_class path module parameter or kernel boot param
0013 o /lib/firmware/updates/UTS_RELEASE
0014 o /lib/firmware/updates
0015 o /lib/firmware/UTS_RELEASE
0016 o /lib/firmware
0017
0018 Enabling this feature only increases your kernel image by about
0019 828 bytes, enable this option unless you are certain you don't
0020 need firmware.
0021
0022 You typically want this built-in (=y) but you can also enable this
0023 as a module, in which case the firmware_class module will be built.
0024 You also want to be sure to enable this built-in if you are going to
0025 enable built-in firmware (CONFIG_EXTRA_FIRMWARE).
0026
0027 if FW_LOADER
0028
0029 config FW_LOADER_PAGED_BUF
0030 bool
0031
0032 config FW_LOADER_SYSFS
0033 bool
0034
0035 config EXTRA_FIRMWARE
0036 string "Build named firmware blobs into the kernel binary"
0037 help
0038 Device drivers which require firmware can typically deal with
0039 having the kernel load firmware from the various supported
0040 /lib/firmware/ paths. This option enables you to build into the
0041 kernel firmware files. Built-in firmware searches are preceded
0042 over firmware lookups using your filesystem over the supported
0043 /lib/firmware paths documented on CONFIG_FW_LOADER.
0044
0045 This may be useful for testing or if the firmware is required early on
0046 in boot and cannot rely on the firmware being placed in an initrd or
0047 initramfs.
0048
0049 This option is a string and takes the (space-separated) names of the
0050 firmware files -- the same names that appear in MODULE_FIRMWARE()
0051 and request_firmware() in the source. These files should exist under
0052 the directory specified by the EXTRA_FIRMWARE_DIR option, which is
0053 /lib/firmware by default.
0054
0055 For example, you might set CONFIG_EXTRA_FIRMWARE="usb8388.bin", copy
0056 the usb8388.bin file into /lib/firmware, and build the kernel. Then
0057 any request_firmware("usb8388.bin") will be satisfied internally
0058 inside the kernel without ever looking at your filesystem at runtime.
0059
0060 WARNING: If you include additional firmware files into your binary
0061 kernel image that are not available under the terms of the GPL,
0062 then it may be a violation of the GPL to distribute the resulting
0063 image since it combines both GPL and non-GPL work. You should
0064 consult a lawyer of your own before distributing such an image.
0065
0066 NOTE: Compressed files are not supported in EXTRA_FIRMWARE.
0067
0068 config EXTRA_FIRMWARE_DIR
0069 string "Firmware blobs root directory"
0070 depends on EXTRA_FIRMWARE != ""
0071 default "/lib/firmware"
0072 help
0073 This option controls the directory in which the kernel build system
0074 looks for the firmware files listed in the EXTRA_FIRMWARE option.
0075
0076 config FW_LOADER_USER_HELPER
0077 bool "Enable the firmware sysfs fallback mechanism"
0078 select FW_LOADER_SYSFS
0079 select FW_LOADER_PAGED_BUF
0080 help
0081 This option enables a sysfs loading facility to enable firmware
0082 loading to the kernel through userspace as a fallback mechanism
0083 if and only if the kernel's direct filesystem lookup for the
0084 firmware failed using the different /lib/firmware/ paths, or the
0085 path specified in the firmware_class path module parameter, or the
0086 firmware_class path kernel boot parameter if the firmware_class is
0087 built-in. For details on how to work with the sysfs fallback mechanism
0088 refer to Documentation/driver-api/firmware/fallback-mechanisms.rst.
0089
0090 The direct filesystem lookup for firmware is always used first now.
0091
0092 If the kernel's direct filesystem lookup for firmware fails to find
0093 the requested firmware a sysfs fallback loading facility is made
0094 available and userspace is informed about this through uevents.
0095 The uevent can be suppressed if the driver explicitly requested it,
0096 this is known as the driver using the custom fallback mechanism.
0097 If the custom fallback mechanism is used userspace must always
0098 acknowledge failure to find firmware as the timeout for the fallback
0099 mechanism is disabled, and failed requests will linger forever.
0100
0101 This used to be the default firmware loading facility, and udev used
0102 to listen for uvents to load firmware for the kernel. The firmware
0103 loading facility functionality in udev has been removed, as such it
0104 can no longer be relied upon as a fallback mechanism. Linux no longer
0105 relies on or uses a fallback mechanism in userspace. If you need to
0106 rely on one refer to the permissively licensed firmwared:
0107
0108 https://github.com/teg/firmwared
0109
0110 Since this was the default firmware loading facility at one point,
0111 old userspace may exist which relies upon it, and as such this
0112 mechanism can never be removed from the kernel.
0113
0114 You should only enable this functionality if you are certain you
0115 require a fallback mechanism and have a userspace mechanism ready to
0116 load firmware in case it is not found. One main reason for this may
0117 be if you have drivers which require firmware built-in and for
0118 whatever reason cannot place the required firmware in initramfs.
0119 Another reason kernels may have this feature enabled is to support a
0120 driver which explicitly relies on this fallback mechanism. Only two
0121 drivers need this today:
0122
0123 o CONFIG_LEDS_LP55XX_COMMON
0124 o CONFIG_DELL_RBU
0125
0126 Outside of supporting the above drivers, another reason for needing
0127 this may be that your firmware resides outside of the paths the kernel
0128 looks for and cannot possibly be specified using the firmware_class
0129 path module parameter or kernel firmware_class path boot parameter
0130 if firmware_class is built-in.
0131
0132 A modern use case may be to temporarily mount a custom partition
0133 during provisioning which is only accessible to userspace, and then
0134 to use it to look for and fetch the required firmware. Such type of
0135 driver functionality may not even ever be desirable upstream by
0136 vendors, and as such is only required to be supported as an interface
0137 for provisioning. Since udev's firmware loading facility has been
0138 removed you can use firmwared or a fork of it to customize how you
0139 want to load firmware based on uevents issued.
0140
0141 Enabling this option will increase your kernel image size by about
0142 13436 bytes.
0143
0144 If you are unsure about this, say N here, unless you are Linux
0145 distribution and need to support the above two drivers, or you are
0146 certain you need to support some really custom firmware loading
0147 facility in userspace.
0148
0149 config FW_LOADER_USER_HELPER_FALLBACK
0150 bool "Force the firmware sysfs fallback mechanism when possible"
0151 depends on FW_LOADER_USER_HELPER
0152 help
0153 Enabling this option forces a sysfs userspace fallback mechanism
0154 to be used for all firmware requests which explicitly do not disable a
0155 a fallback mechanism. Firmware calls which do prohibit a fallback
0156 mechanism is request_firmware_direct(). This option is kept for
0157 backward compatibility purposes given this precise mechanism can also
0158 be enabled by setting the proc sysctl value to true:
0159
0160 /proc/sys/kernel/firmware_config/force_sysfs_fallback
0161
0162 If you are unsure about this, say N here.
0163
0164 config FW_LOADER_COMPRESS
0165 bool "Enable compressed firmware support"
0166 help
0167 This option enables the support for loading compressed firmware
0168 files. The caller of firmware API receives the decompressed file
0169 content. The compressed file is loaded as a fallback, only after
0170 loading the raw file failed at first.
0171
0172 Compressed firmware support does not apply to firmware images
0173 that are built into the kernel image (CONFIG_EXTRA_FIRMWARE).
0174
0175 if FW_LOADER_COMPRESS
0176 config FW_LOADER_COMPRESS_XZ
0177 bool "Enable XZ-compressed firmware support"
0178 select FW_LOADER_PAGED_BUF
0179 select XZ_DEC
0180 default y
0181 help
0182 This option adds the support for XZ-compressed files.
0183 The files have to be compressed with either none or crc32
0184 integrity check type (pass "-C crc32" option to xz command).
0185
0186 config FW_LOADER_COMPRESS_ZSTD
0187 bool "Enable ZSTD-compressed firmware support"
0188 select ZSTD_DECOMPRESS
0189 help
0190 This option adds the support for ZSTD-compressed files.
0191
0192 endif # FW_LOADER_COMPRESS
0193
0194 config FW_CACHE
0195 bool "Enable firmware caching during suspend"
0196 depends on PM_SLEEP
0197 default y if PM_SLEEP
0198 help
0199 Because firmware caching generates uevent messages that are sent
0200 over a netlink socket, it can prevent suspend on many platforms.
0201 It is also not always useful, so on such platforms we have the
0202 option.
0203
0204 If unsure, say Y.
0205
0206 config FW_UPLOAD
0207 bool "Enable users to initiate firmware updates using sysfs"
0208 select FW_LOADER_SYSFS
0209 select FW_LOADER_PAGED_BUF
0210 help
0211 Enabling this option will allow device drivers to expose a persistent
0212 sysfs interface that allows firmware updates to be initiated from
0213 userspace. For example, FPGA based PCIe cards load firmware and FPGA
0214 images from local FLASH when the card boots. The images in FLASH may
0215 be updated with new images provided by the user. Enable this device
0216 to support cards that rely on user-initiated updates for firmware files.
0217
0218 If unsure, say N.
0219
0220 endif # FW_LOADER
0221 endmenu
