drivers/base/firmware_loader/Kconfig

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