Re: [PATCH 3/5] firmware: revamp firmware documentation

[Daniel Wagner <daniel.wagner@bmw-carit.de>]

> +++ b/Documentation/driver-api/firmware/built-in-fw.rst
> @@ -0,0 +1,36 @@
> +=================
> +Built-in firmware
> +=================
> +
> +Firmware can be built-in to the kernel, that is built-in to vmlinux,
> +to enable firmware lookups to avoid having to look for firmware from
> +the filesystem.

I find the second part of the sentence a bit confusing in the wording.

> You can enable built-in firmware using the kernel
> +configuration options:
> +
> +  * CONFIG_EXTRA_FIRMWARE
> +  * CONFIG_EXTRA_FIRMWARE_DIR
> +
> +The should not be confused with CONFIG_FIRMWARE_IN_KERNEL, this is for drivers

s/The/This/ ?

> +which enable firmware to be built as part of the kernel build process. This

enables?

> +option, CONFIG_FIRMWARE_IN_KERNEL, will build all firmware for all drivers
> +enabled which ship its firmware inside the Linux kernel source tree.
> +
> +There are a few reasons why you might want to consider building your firmware
> +into the kernel with CONFIG_EXTRA_FIRMWARE though:
> +
> +* Speed
> +* Firmware is needed for accessing the boot device, and the user doesn't
> +  want to stuff the firmware into the boot initramfs.
> +
> +Even if you have these needs there are a few reasons why you may not be
> +able to make use of built-in firmware:
> +
> +* Legalese - firmware is non-GPL compatible
> +* Some firmware may be optional
> +* Firmware upgrades are possible, therefore a new firmware would implicate
> +  a complete firmware rebuild.

kernel rebuild?

> +* Some firmware files may be really large in size. The remote-proc subsystem
> +  is an example subsystem which deals with these sorts of firmware
> +* The firmware may need to be scraped out from some device specific location
> +  dynamically, an example is calibration data for for some WiFi chipsets.

Maybe it is worth to mention, that the calibration data is unique to a 
given chip, so it is individual. That is you would need to built for 
each device you sell its own kernel.

[...]

> +++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst
> @@ -0,0 +1,195 @@
> +===================
> +Fallback mechanisms
> +===================
> +
> +A fallback mechanism is supported to allow to overcome failures to do a direct
> +filesystem lookup on the root filesystem or when the firmware simply cannot be
> +installed for practical reasons on the root filesystem. The kernel
> +configuration options related to supporting the firmware fallback mechanism are:
> +
> +  * CONFIG_FW_LOADER_USER_HELPER: enables building the firmware fallback
> +    mechanism. Most distributions enable this option today. If enabled but
> +    CONFIG_FW_LOADER_USER_HELPER_FALLBACK is disabled, only the custom fallback
> +    mechanism is available and for the request_firmware_nowait() call.
> +  * CONFIG_FW_LOADER_USER_HELPER_FALLBACK: force enables each request to
> +    enable the kobject uevent fallback mechanism on all firmare API calls

s/firmare/firmware/

> +    except request_firmware_direct(). Most distributions disable this option
> +    today. The call request_firmware_nowait() allows for one alternative
> +    fallback mechanism: if this kconfig option is enabled and your second
> +    argument to request_firmware_nowait(), uevent, is set to false you are
> +    informing the kernel that you have a custom fallback mechanism and it will
> +    manually load the firmware. Read below for more details.
> +
> +Note that this means when having this configuration:
> +
> +CONFIG_FW_LOADER_USER_HELPER=y
> +CONFIG_FW_LOADER_USER_HELPER_FALLBACK=n
> +
> +the kobject uevent fallback mechanism will never take effect even
> +for request_firmware_nowait() when uevent is set to true.
> +
> +Justifying the firmware fallback mechanism
> +==========================================
> +
> +Direct filesystem lookups may fail for a variety of reasons. Known reasons for
> +this are worth itemizing and documenting as it justifies the need for the
> +fallback mechanism:
> +
> +* Race against access with the root filesystem upon bootup.
> +
> +* Races upon resume from suspend. This is resolved by the firmware cache, but
> +  the firmware cache is only supported if you use uevents, and its not
> +  supported for request_firmware_into_buf().
> +
> +* Firmware is not accessible through typical means:
> +        * It cannot be installed into the root filesystem
> +        * The firmware provides very unique device specific data tailored for
> +          the unit gathered with local information. An example is calibration
> +          data for WiFi chipsets for mobile devices. This calibration data is
> +          not common to all units, but tailored per unit.  Such information may
> +          be installed on a separate flash partition other than where the root
> +          filesystem is provided.

Ah, her is the bit about the calibration information.

cheers,
daniel