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

[Luis R. Rodriguez]

On Tue, Dec 13, 2016 at 02:26:06PM +0100, Daniel Wagner wrote:
> > +++ 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.

OK how about:

Firmware can be built-in to the kernel, this means building the firmware        
into vmlinux directly, to enable avoiding having to look for firmware from      
the filesystem. Instead, firmware can be looked for inside the kernel           
directly. You can enable built-in firmware using the kernel configuration       
options:                                                                        
                                                                                
  * CONFIG_EXTRA_FIRMWARE                                                       
  * CONFIG_EXTRA_FIRMWARE_DIR   

> > 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/ ?

Fixed.

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

Fixed.

> > +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?

Fixed.

> > +* 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.

Adjusted. It now says:

* The firmware may need to be scraped out from some device specific location    
  dynamically, an example is calibration data for for some WiFi chipsets. This  
  calibration data can be unique per sold device.  

> [...]
> 
> > +++ 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/

Fixed.

  Luis