Re: [PATCH v6 05/13] firmware_loader: enhance Kconfig documentation over FW_LOADER

Kees Cook
2018-05-08T22:42:33Z

On Tue, May 8, 2018 at 11:12 AM, Luis R. Rodriguez <mcgrof@kernel.org> wrote:
> If you try to read FW_LOADER today it speaks of old riddles and
> unless you have been following development closely you will loose

Typo: 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 compartamentalize and make it clearer which

Typo: compartmentalize

> 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
>
> Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
> ---
> drivers/base/Kconfig | 165 ++++++++++++++++++++++++++++++++++---------
> 1 file changed, 131 insertions(+), 34 deletions(-)
>
> diff --git a/drivers/base/Kconfig b/drivers/base/Kconfig
> index 29b0eb452b3a..a4fe86caecca 100644
> --- a/drivers/base/Kconfig
> +++ b/drivers/base/Kconfig
> @@ -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 firmwar at kernel build time. These drivers do not use the

Typo: firmware

> + 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 these firmware blobs into the kernel binary"

Maybe "Build named firmware blobs ..." "these" took me a while to figure out.

> 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 preceeded

Typo: 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 firwmare is always used first now.

Typo: firmware

> +
> + If the kernel's direct filesystem lookup for firware 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 supressed 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:

Typo: firmware

> +
> + 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 possibily 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
> --
> 2.17.0
>

-Kees

--
Kees Cook
Pixel Security