From: "Luis R. Rodriguez" <firstname.lastname@example.org>
Cc: email@example.com, firstname.lastname@example.org,
email@example.com, firstname.lastname@example.org, email@example.com,
firstname.lastname@example.org, email@example.com, firstname.lastname@example.org,
email@example.com, firstname.lastname@example.org, email@example.com,
firstname.lastname@example.org, email@example.com, firstname.lastname@example.org,
email@example.com, firstname.lastname@example.org, email@example.com,
firstname.lastname@example.org, email@example.com, firstname.lastname@example.org,
email@example.com, firstname.lastname@example.org, email@example.com,
firstname.lastname@example.org, email@example.com, firstname.lastname@example.org,
"Luis R. Rodriguez" <email@example.com>
Subject: [PATCH v7 05/14] firmware_loader: enhance Kconfig documentation over FW_LOADER
Date: Thu, 10 May 2018 13:08:41 -0700 [thread overview]
Message-ID: <firstname.lastname@example.org> (raw)
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/
This also now recommends using firmwared  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.
Reviewed-by: Kees Cook <email@example.com>
Signed-off-by: Luis R. Rodriguez <firstname.lastname@example.org>
drivers/base/Kconfig | 165 ++++++++++++++++++++++++++++++++++---------
1 file changed, 131 insertions(+), 34 deletions(-)
diff --git a/drivers/base/Kconfig b/drivers/base/Kconfig
index 29b0eb452b3a..db2bbe483927 100644
@@ -70,39 +70,64 @@ config STANDALONE
If unsure, say Y.
- bool "Prevent firmware from being built"
+ bool "Disable drivers features which enable custom firmware building"
- 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
+ o CONFIG_WANXL through CONFIG_WANXL_BUILD_FIRMWARE
+ o CONFIG_SCSI_AIC79XX through CONFIG_AIC79XX_BUILD_FIRMWARE
+menu "Firmware loader"
- tristate "Userspace firmware loading support" if EXPERT
+ tristate "Firmware loading facility" if EXPERT
- 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).
- string "External firmware blobs to build into the kernel binary"
- depends on FW_LOADER
+ string "Build named firmware blobs into the kernel binary"
- Various drivers in the kernel source tree may require firmware,
- which is generally available in your distribution's linux-firmware
+ 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
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.
+ bool "Enable the firmware sysfs fallback mechanism"
+ 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:
+ 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.
- 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
- 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:
If you are unsure about this, say N here.
+endif # FW_LOADER
next prev parent reply other threads:[~2018-05-10 20:09 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-05-10 20:08 [PATCH v7 00/14] firmware_loader changes for v4.18 Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 01/14] firmware: wrap FW_OPT_* into an enum Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 02/14] firmware: use () to terminate kernel-doc function names Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 03/14] firmware: rename fw_sysfs_fallback to firmware_fallback_sysfs() Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 04/14] firmware_loader: document firmware_sysfs_fallback() Luis R. Rodriguez
2018-05-10 20:08 ` Luis R. Rodriguez [this message]
2018-05-10 20:08 ` [PATCH v7 06/14] firmware_loader: replace ---help--- with help Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 07/14] firmware_loader: move kconfig FW_LOADER entries to its own file Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 08/14] firmware_loader: make firmware_fallback_sysfs() print more useful Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 09/14] firmware: add firmware_request_nowarn() - load firmware without warnings Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 10/14] ath10k: use firmware_request_nowarn() to load firmware Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 11/14] ath10k: re-enable the firmware fallback mechanism for testmode Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 12/14] Documentation: fix few typos and clarifications for the firmware loader Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 13/14] Documentation: remove stale firmware API reference Luis R. Rodriguez
2018-05-10 20:08 ` [PATCH v7 14/14] Documentation: clarify firmware_class provenance and why we can't rename the module Luis R. Rodriguez
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).