linux-kernel - [PATCH v5 4/6] firmware_loader: document firmware_sysfs

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20180504174356.13227-5-mcgrof@kernel.org>
Date:   Fri,  4 May 2018 10:43:53 -0700
From:   "Luis R. Rodriguez" <mcgrof@...nel.org>
To:     gregkh@...uxfoundation.org
Cc:     akpm@...ux-foundation.org, keescook@...omium.org,
        josh@...htriplett.org, teg@...m.no, wagi@...om.org,
        hdegoede@...hat.com, andresx7@...il.com, zohar@...ux.vnet.ibm.com,
        kubakici@...pl, shuah@...nel.org, mfuzzey@...keon.com,
        dhowells@...hat.com, pali.rohar@...il.com, tiwai@...e.de,
        kvalo@...eaurora.org, arend.vanspriel@...adcom.com,
        zajec5@...il.com, nbroeking@...com, markivx@...eaurora.org,
        broonie@...nel.org, dmitry.torokhov@...il.com, dwmw2@...radead.org,
        torvalds@...ux-foundation.org, Abhay_Salunke@...l.com,
        bjorn.andersson@...aro.org, jewalt@...innovations.com,
        oneukum@...e.com, cantabile.desu@...il.com, ast@...com,
        hare@...e.com, jejb@...ux.vnet.ibm.com, martin.petersen@...cle.com,
        khc@...waw.pl, davem@...emloft.net, maco@...roid.com,
        arve@...roid.com, tkjos@...roid.com, linux-kernel@...r.kernel.org,
        linux-fsdevel@...r.kernel.org, linux-scsi@...r.kernel.org,
        linux-wireless@...r.kernel.org, netdev@...r.kernel.org,
        "Luis R. Rodriguez" <mcgrof@...nel.org>
Subject: [PATCH v5 4/6] firmware_loader: document firmware_sysfs_fallback()

This also sets the expecations for future fallback interfaces, even
if they are not exported.

Signed-off-by: Luis R. Rodriguez <mcgrof@...nel.org>
---
 drivers/base/firmware_loader/fallback.c | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/drivers/base/firmware_loader/fallback.c b/drivers/base/firmware_loader/fallback.c
index 3db9e0f225ac..9169e7b9800c 100644
--- a/drivers/base/firmware_loader/fallback.c
+++ b/drivers/base/firmware_loader/fallback.c
@@ -662,6 +662,26 @@ static bool fw_run_sysfs_fallback(enum fw_opt opt_flags)
 	return fw_force_sysfs_fallback(opt_flags);
 }
 
+/**
+ * firmware_fallback_sysfs() - use the fallback mechanism to find firmware
+ * @fw: pointer to firmware image
+ * @name: name of firmware file to look for
+ * @device: device for which firmware is being loaded
+ * @opt_flags: options to control firmware loading behaviour
+ * @ret: return value from direct lookup which triggered the fallback mechanism
+ *
+ * This function is called if direct lookup for the firmware failed, it enables
+ * a fallback mechanism through userspace by exposing a sysfs loading
+ * interface. Userspace is in charge of loading the firmware through the syfs
+ * loading interface. This syfs fallback mechanism may be disabled completely
+ * on a system by setting the proc sysctl value ignore_sysfs_fallback to true.
+ * If this false we check if the internal API caller set the @FW_OPT_NOFALLBACK
+ * flag, if so it would also disable the fallback mechanism. A system may want
+ * to enfoce the sysfs fallback mechanism at all times, it can do this by
+ * setting ignore_sysfs_fallback to false and force_sysfs_fallback to true.
+ * Enabling force_sysfs_fallback is functionally equivalent to build a kernel
+ * with CONFIG_FW_LOADER_USER_HELPER_FALLBACK.
+ **/
 int firmware_fallback_sysfs(struct firmware *fw, const char *name,
 			    struct device *device,
 			    enum fw_opt opt_flags,
-- 
2.17.0