firmware_loader: enhance Kconfig documentation over FW_LOADER
If you try to read FW_LOADER today it speaks of old riddles and unless you have been following development closely you will lose track of what is what. Even the documentation for PREVENT_FIRMWARE_BUILD is a bit fuzzy and how it fits into this big picture. Give the FW_LOADER kconfig documentation some love with more up to date developments and recommendations. While at it, wrap the FW_LOADER code into its own menu to compartmentalize and make it clearer which components really are part of the FW_LOADER. This should also make it easier to later move these kconfig entries into the firmware_loader/ directory later. This also now recommends using firmwared [0] for folks left needing a uevent handler in userspace for the sysfs firmware fallback mechanis given udev's uevent firmware mechanism was ripped out a while ago. [0] https://github.com/teg/firmwared Reviewed-by: Kees Cook <keescook@chromium.org> Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org> Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
This commit is contained in:
Luis R. Rodriguez
Greg Kroah-Hartman
parent
84b5c4fec7
commit
02c3993068
@ -70,39 +70,64 @@ config STANDALONE
|
||||
If unsure, say Y.
|
||||
|
||||
config PREVENT_FIRMWARE_BUILD
|
||||
bool "Prevent firmware from being built"
|
||||
bool "Disable drivers features which enable custom firmware building"
|
||||
default y
|
||||
help
|
||||
Say yes to avoid building firmware. Firmware is usually shipped
|
||||
with the driver and only when updating the firmware should a
|
||||
rebuild be made.
|
||||
If unsure, say Y here.
|
||||
Say yes to disable driver features which enable building a custom
|
||||
driver firmware at kernel build time. These drivers do not use the
|
||||
kernel firmware API to load firmware (CONFIG_FW_LOADER), instead they
|
||||
use their own custom loading mechanism. The required firmware is
|
||||
usually shipped with the driver, building the driver firmware
|
||||
should only be needed if you have an updated firmware source.
|
||||
|
||||
Firmware should not be being built as part of kernel, these days
|
||||
you should always prevent this and say Y here. There are only two
|
||||
old drivers which enable building of its firmware at kernel build
|
||||
time:
|
||||
|
||||
o CONFIG_WANXL through CONFIG_WANXL_BUILD_FIRMWARE
|
||||
o CONFIG_SCSI_AIC79XX through CONFIG_AIC79XX_BUILD_FIRMWARE
|
||||
|
||||
menu "Firmware loader"
|
||||
|
||||
config FW_LOADER
|
||||
tristate "Userspace firmware loading support" if EXPERT
|
||||
tristate "Firmware loading facility" if EXPERT
|
||||
default y
|
||||
---help---
|
||||
This option is provided for the case where none of the in-tree modules
|
||||
require userspace firmware loading support, but a module built
|
||||
out-of-tree does.
|
||||
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).
|
||||
|
||||
if FW_LOADER
|
||||
|
||||
config EXTRA_FIRMWARE
|
||||
string "External firmware blobs to build into the kernel binary"
|
||||
depends on FW_LOADER
|
||||
string "Build named firmware blobs into the kernel binary"
|
||||
help
|
||||
Various drivers in the kernel source tree may require firmware,
|
||||
which is generally available in your distribution's linux-firmware
|
||||
package.
|
||||
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.
|
||||
|
||||
The linux-firmware package should install firmware into
|
||||
/lib/firmware/ on your system, so they can be loaded by userspace
|
||||
helpers on request.
|
||||
|
||||
This option allows firmware to be built into the kernel for the case
|
||||
where the user either cannot or doesn't want to provide it from
|
||||
userspace at runtime (for example, when the firmware in question is
|
||||
required for accessing the boot device, and the user doesn't want to
|
||||
use an initrd).
|
||||
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()
|
||||
@ -113,7 +138,7 @@ config EXTRA_FIRMWARE
|
||||
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
|
||||
without needing to call out to userspace.
|
||||
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,
|
||||
@ -130,22 +155,94 @@ config EXTRA_FIRMWARE_DIR
|
||||
looks for the firmware files listed in the EXTRA_FIRMWARE option.
|
||||
|
||||
config FW_LOADER_USER_HELPER
|
||||
bool
|
||||
bool "Enable the firmware sysfs fallback mechanism"
|
||||
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 "Fallback user-helper invocation for firmware loading"
|
||||
depends on FW_LOADER
|
||||
select FW_LOADER_USER_HELPER
|
||||
bool "Force the firmware sysfs fallback mechanism when possible"
|
||||
depends on FW_LOADER_USER_HELPER
|
||||
help
|
||||
This option enables / disables the invocation of user-helper
|
||||
(e.g. udev) for loading firmware files as a fallback after the
|
||||
direct file loading in kernel fails. The user-mode helper is
|
||||
no longer required unless you have a special firmware file that
|
||||
resides in a non-standard path. Moreover, the udev support has
|
||||
been deprecated upstream.
|
||||
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.
|
||||
|
||||
endif # FW_LOADER
|
||||
endmenu
|
||||
|
||||
config WANT_DEV_COREDUMP
|
||||
bool
|
||||
help
|
||||
|
||||
Loading…
Reference in New Issue
Block a user