Subject: Re: [PATCH 3/5] firmware: revamp firmware documentation
To: "Luis R. Rodriguez" <mcgrof@kernel.org>, gregkh@linuxfoundation.org,
        ming.lei@canonical.com
References: <20161213030828.17820-1-mcgrof@kernel.org>
 <20161213030828.17820-4-mcgrof@kernel.org>
Cc: daniel.wagner@bmw-carit.de, teg@jklm.no, mchehab@osg.samsung.com,
        linux-kernel@vger.kernel.org, markivx@codeaurora.org,
        stephen.boyd@linaro.org, broonie@kernel.org, zohar@linux.vnet.ibm.com,
        tiwai@suse.de, johannes@sipsolutions.net, chunkeey@googlemail.com,
        hauke@hauke-m.de, jwboyer@fedoraproject.org, dmitry.torokhov@gmail.com,
        dwmw2@infradead.org, jslaby@suse.com, torvalds@linux-foundation.org,
        luto@amacapital.net, fengguang.wu@intel.com, rpurdie@rpsys.net,
        j.anaszewski@samsung.com, Abhay_Salunke@dell.com, Julia.Lawall@lip6.fr,
        Gilles.Muller@lip6.fr, nicolas.palix@imag.fr, dhowells@redhat.com,
        bjorn.andersson@linaro.org, arend.vanspriel@broadcom.com,
        kvalo@codeaurora.org
From: =?UTF-8?B?UmFmYcWCIE1pxYJlY2tp?= <zajec5@gmail.com>
Message-ID: <1daef7df-5a0d-894b-802c-e9622082570f@gmail.com>
Date: Tue, 13 Dec 2016 08:26:41 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101
 Thunderbird/45.4.0
MIME-Version: 1.0
In-Reply-To: <20161213030828.17820-4-mcgrof@kernel.org>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 2353
Lines: 48

On 12/13/2016 04:08 AM, Luis R. Rodriguez wrote:
> Understanding this code is getting out of control without any
> notes. Give the firmware_class driver a much needed documentation love,
> and while at it convert it to the new sphinx documentation format.

It does help to understand the class/API, thank you!


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

Could it be you meant "kernel rebuild" or "vmlinux rebuild" here?


> diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst b/Documentation/driver-api/firmware/fallback-mechanisms.rst
> new file mode 100644
> index 000000000000..edce1d76ce29
> --- /dev/null
> +++ 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
> +    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.

Yeah, it really asks for API simplification ;)