| # SPDX-License-Identifier: GPL-2.0 |
| menu "Firmware loader" |
| |
| config FW_LOADER |
| tristate "Firmware loading facility" if EXPERT |
| select CRYPTO_HASH if FW_LOADER_DEBUG |
| select CRYPTO_SHA256 if FW_LOADER_DEBUG |
| default y |
| help |
| This enables the firmware loading facility in the kernel. The kernel |
| will first look for built-in firmware, if it has any. Next, it will |
| look for the requested firmware in a series of filesystem paths: |
| |
| o firmware_class path module parameter or kernel boot param |
| o /lib/firmware/updates/UTS_RELEASE |
| o /lib/firmware/updates |
| o /lib/firmware/UTS_RELEASE |
| o /lib/firmware |
| |
| Enabling this feature only increases your kernel image by about |
| 828 bytes, enable this option unless you are certain you don't |
| need firmware. |
| |
| You typically want this built-in (=y) but you can also enable this |
| as a module, in which case the firmware_class module will be built. |
| You also want to be sure to enable this built-in if you are going to |
| enable built-in firmware (CONFIG_EXTRA_FIRMWARE). |
| |
| config FW_LOADER_DEBUG |
| bool "Log filenames and checksums for loaded firmware" |
| depends on CRYPTO = FW_LOADER || CRYPTO=y |
| depends on DYNAMIC_DEBUG |
| depends on FW_LOADER |
| default FW_LOADER |
| help |
| Select this option to use dynamic debug to log firmware filenames and |
| SHA256 checksums to the kernel log for each firmware file that is |
| loaded. |
| |
| config RUST_FW_LOADER_ABSTRACTIONS |
| bool "Rust Firmware Loader abstractions" |
| depends on RUST |
| depends on FW_LOADER=y |
| help |
| This enables the Rust abstractions for the firmware loader API. |
| |
| if FW_LOADER |
| |
| config FW_LOADER_PAGED_BUF |
| bool |
| |
| config FW_LOADER_SYSFS |
| bool |
| |
| config EXTRA_FIRMWARE |
| string "Build named firmware blobs into the kernel binary" |
| help |
| Device drivers which require firmware can typically deal with |
| having the kernel load firmware from the various supported |
| /lib/firmware/ paths. This option enables you to build into the |
| kernel firmware files. Built-in firmware searches are preceded |
| over firmware lookups using your filesystem over the supported |
| /lib/firmware paths documented on CONFIG_FW_LOADER. |
| |
| This may be useful for testing or if the firmware is required early on |
| in boot and cannot rely on the firmware being placed in an initrd or |
| initramfs. |
| |
| This option is a string and takes the (space-separated) names of the |
| firmware files -- the same names that appear in MODULE_FIRMWARE() |
| and request_firmware() in the source. These files should exist under |
| the directory specified by the EXTRA_FIRMWARE_DIR option, which is |
| /lib/firmware by default. |
| |
| For example, you might set CONFIG_EXTRA_FIRMWARE="usb8388.bin", copy |
| the usb8388.bin file into /lib/firmware, and build the kernel. Then |
| any request_firmware("usb8388.bin") will be satisfied internally |
| inside the kernel without ever looking at your filesystem at runtime. |
| |
| WARNING: If you include additional firmware files into your binary |
| kernel image that are not available under the terms of the GPL, |
| then it may be a violation of the GPL to distribute the resulting |
| image since it combines both GPL and non-GPL work. You should |
| consult a lawyer of your own before distributing such an image. |
| |
| NOTE: Compressed files are not supported in EXTRA_FIRMWARE. |
| |
| config EXTRA_FIRMWARE_DIR |
| string "Firmware blobs root directory" |
| depends on EXTRA_FIRMWARE != "" |
| default "/lib/firmware" |
| help |
| This option controls the directory in which the kernel build system |
| looks for the firmware files listed in the EXTRA_FIRMWARE option. |
| |
| config FW_LOADER_USER_HELPER |
| bool "Enable the firmware sysfs fallback mechanism" |
| select FW_LOADER_SYSFS |
| select FW_LOADER_PAGED_BUF |
| help |
| This option enables a sysfs loading facility to enable firmware |
| loading to the kernel through userspace as a fallback mechanism |
| if and only if the kernel's direct filesystem lookup for the |
| firmware failed using the different /lib/firmware/ paths, or the |
| path specified in the firmware_class path module parameter, or the |
| firmware_class path kernel boot parameter if the firmware_class is |
| built-in. For details on how to work with the sysfs fallback mechanism |
| refer to Documentation/driver-api/firmware/fallback-mechanisms.rst. |
| |
| The direct filesystem lookup for firmware is always used first now. |
| |
| If the kernel's direct filesystem lookup for firmware fails to find |
| the requested firmware a sysfs fallback loading facility is made |
| available and userspace is informed about this through uevents. |
| The uevent can be suppressed if the driver explicitly requested it, |
| this is known as the driver using the custom fallback mechanism. |
| If the custom fallback mechanism is used userspace must always |
| acknowledge failure to find firmware as the timeout for the fallback |
| mechanism is disabled, and failed requests will linger forever. |
| |
| This used to be the default firmware loading facility, and udev used |
| to listen for uvents to load firmware for the kernel. The firmware |
| loading facility functionality in udev has been removed, as such it |
| can no longer be relied upon as a fallback mechanism. Linux no longer |
| relies on or uses a fallback mechanism in userspace. If you need to |
| rely on one refer to the permissively licensed firmwared: |
| |
| https://github.com/teg/firmwared |
| |
| Since this was the default firmware loading facility at one point, |
| old userspace may exist which relies upon it, and as such this |
| mechanism can never be removed from the kernel. |
| |
| You should only enable this functionality if you are certain you |
| require a fallback mechanism and have a userspace mechanism ready to |
| load firmware in case it is not found. One main reason for this may |
| be if you have drivers which require firmware built-in and for |
| whatever reason cannot place the required firmware in initramfs. |
| Another reason kernels may have this feature enabled is to support a |
| driver which explicitly relies on this fallback mechanism. Only two |
| drivers need this today: |
| |
| o CONFIG_LEDS_LP55XX_COMMON |
| o CONFIG_DELL_RBU |
| |
| Outside of supporting the above drivers, another reason for needing |
| this may be that your firmware resides outside of the paths the kernel |
| looks for and cannot possibly be specified using the firmware_class |
| path module parameter or kernel firmware_class path boot parameter |
| if firmware_class is built-in. |
| |
| A modern use case may be to temporarily mount a custom partition |
| during provisioning which is only accessible to userspace, and then |
| to use it to look for and fetch the required firmware. Such type of |
| driver functionality may not even ever be desirable upstream by |
| vendors, and as such is only required to be supported as an interface |
| for provisioning. Since udev's firmware loading facility has been |
| removed you can use firmwared or a fork of it to customize how you |
| want to load firmware based on uevents issued. |
| |
| Enabling this option will increase your kernel image size by about |
| 13436 bytes. |
| |
| If you are unsure about this, say N here, unless you are Linux |
| distribution and need to support the above two drivers, or you are |
| certain you need to support some really custom firmware loading |
| facility in userspace. |
| |
| config FW_LOADER_USER_HELPER_FALLBACK |
| bool "Force the firmware sysfs fallback mechanism when possible" |
| depends on FW_LOADER_USER_HELPER |
| help |
| Enabling this option forces a sysfs userspace fallback mechanism |
| to be used for all firmware requests which explicitly do not disable a |
| a fallback mechanism. Firmware calls which do prohibit a fallback |
| mechanism is request_firmware_direct(). This option is kept for |
| backward compatibility purposes given this precise mechanism can also |
| be enabled by setting the proc sysctl value to true: |
| |
| /proc/sys/kernel/firmware_config/force_sysfs_fallback |
| |
| If you are unsure about this, say N here. |
| |
| config FW_LOADER_COMPRESS |
| bool "Enable compressed firmware support" |
| help |
| This option enables the support for loading compressed firmware |
| files. The caller of firmware API receives the decompressed file |
| content. The compressed file is loaded as a fallback, only after |
| loading the raw file failed at first. |
| |
| Compressed firmware support does not apply to firmware images |
| that are built into the kernel image (CONFIG_EXTRA_FIRMWARE). |
| |
| if FW_LOADER_COMPRESS |
| config FW_LOADER_COMPRESS_XZ |
| bool "Enable XZ-compressed firmware support" |
| select FW_LOADER_PAGED_BUF |
| select XZ_DEC |
| default y |
| help |
| This option adds the support for XZ-compressed files. |
| The files have to be compressed with either none or crc32 |
| integrity check type (pass "-C crc32" option to xz command). |
| |
| config FW_LOADER_COMPRESS_ZSTD |
| bool "Enable ZSTD-compressed firmware support" |
| select ZSTD_DECOMPRESS |
| help |
| This option adds the support for ZSTD-compressed files. |
| |
| endif # FW_LOADER_COMPRESS |
| |
| config FW_CACHE |
| bool "Enable firmware caching during suspend" |
| depends on PM_SLEEP |
| default y if PM_SLEEP |
| help |
| Because firmware caching generates uevent messages that are sent |
| over a netlink socket, it can prevent suspend on many platforms. |
| It is also not always useful, so on such platforms we have the |
| option. |
| |
| If unsure, say Y. |
| |
| config FW_UPLOAD |
| bool "Enable users to initiate firmware updates using sysfs" |
| select FW_LOADER_SYSFS |
| select FW_LOADER_PAGED_BUF |
| help |
| Enabling this option will allow device drivers to expose a persistent |
| sysfs interface that allows firmware updates to be initiated from |
| userspace. For example, FPGA based PCIe cards load firmware and FPGA |
| images from local FLASH when the card boots. The images in FLASH may |
| be updated with new images provided by the user. Enable this device |
| to support cards that rely on user-initiated updates for firmware files. |
| |
| If unsure, say N. |
| |
| endif # FW_LOADER |
| endmenu |
