firmware: wrap FW_OPT_* into an enum

This should let us associate enum kdoc to these values.
While at it, kdocify the fw_opt.

Signed-off-by: Andres Rodriguez <andresx7@gmail.com>
Reviewed-by: Kees Cook <keescook@chromium.org>
Acked-by: Luis R. Rodriguez <mcgrof@kernel.org>
[mcgrof: coding style fixes, merge kdoc with enum move]
Signed-off-by: Luis R. Rodriguez <mcgrof@kernel.org>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

1 files changed, 29 insertions, 8 deletions

diff --git a/drivers/base/firmware_loader/firmware.h b/drivers/base/firmware_loader/firmware.h
index 64acbb1a392c..4f433b447367 100644
--- a/drivers/base/firmware_loader/firmware.h
+++ b/drivers/base/firmware_loader/firmware.h
@@ -2,6 +2,7 @@
 #ifndef __FIRMWARE_LOADER_H
 #define __FIRMWARE_LOADER_H
 
+#include <linux/bitops.h>
 #include <linux/firmware.h>
 #include <linux/types.h>
 #include <linux/kref.h>
@@ -10,13 +11,33 @@
 
 #include <generated/utsrelease.h>
 
-/* firmware behavior options */
-#define FW_OPT_UEVENT                   (1U << 0)
-#define FW_OPT_NOWAIT                   (1U << 1)
-#define FW_OPT_USERHELPER               (1U << 2)
-#define FW_OPT_NO_WARN                  (1U << 3)
-#define FW_OPT_NOCACHE                  (1U << 4)
-#define FW_OPT_NOFALLBACK               (1U << 5)
+/**
+ * enum fw_opt - options to control firmware loading behaviour
+ *
+ * @FW_OPT_UEVENT: Enables the fallback mechanism to send a kobject uevent
+ *      when the firmware is not found. Userspace is in charge to load the
+ *      firmware using the sysfs loading facility.
+ * @FW_OPT_NOWAIT: Used to describe the firmware request is asynchronous.
+ * @FW_OPT_USERHELPER: Enable the fallback mechanism, in case the direct
+ *      filesystem lookup fails at finding the firmware.  For details refer to
+ *      fw_sysfs_fallback().
+ * @FW_OPT_NO_WARN: Quiet, avoid printing warning messages.
+ * @FW_OPT_NOCACHE: Disables firmware caching. Firmware caching is used to
+ *      cache the firmware upon suspend, so that upon resume races against the
+ *      firmware file lookup on storage is avoided. Used for calls where the
+ *      file may be too big, or where the driver takes charge of its own
+ *      firmware caching mechanism.
+ * @FW_OPT_NOFALLBACK: Disable the fallback mechanism. Takes precedence over
+ *      &FW_OPT_UEVENT and &FW_OPT_USERHELPER.
+ */
+enum fw_opt {
+        FW_OPT_UEVENT =         BIT(0),
+        FW_OPT_NOWAIT =         BIT(1),
+        FW_OPT_USERHELPER =     BIT(2),
+        FW_OPT_NO_WARN =        BIT(3),
+        FW_OPT_NOCACHE =        BIT(4),
+        FW_OPT_NOFALLBACK =     BIT(5),
+};
 
 enum fw_status {
         FW_STATUS_UNKNOWN,
@@ -110,6 +131,6 @@ static inline void fw_state_done(struct fw_priv *fw_priv)
 }
 
 int assign_fw(struct firmware *fw, struct device *device,
-              unsigned int opt_flags);
+              enum fw_opt opt_flags);
 
 #endif /* __FIRMWARE_LOADER_H */