1 /* SPDX-License-Identifier: GPL-2.0 */ 2 #ifndef __FIRMWARE_LOADER_H 3 #define __FIRMWARE_LOADER_H 4 5 #include <linux/bitops.h> 6 #include <linux/firmware.h> 7 #include <linux/types.h> 8 #include <linux/kref.h> 9 #include <linux/list.h> 10 #include <linux/completion.h> 11 12 #include <generated/utsrelease.h> 13 14 /** 15 * enum fw_opt - options to control firmware loading behaviour 16 * 17 * @FW_OPT_UEVENT: Enables the fallback mechanism to send a kobject uevent 18 * when the firmware is not found. Userspace is in charge to load the 19 * firmware using the sysfs loading facility. 20 * @FW_OPT_NOWAIT: Used to describe the firmware request is asynchronous. 21 * @FW_OPT_USERHELPER: Enable the fallback mechanism, in case the direct 22 * filesystem lookup fails at finding the firmware. For details refer to 23 * firmware_fallback_sysfs(). 24 * @FW_OPT_NO_WARN: Quiet, avoid printing warning messages. 25 * @FW_OPT_NOCACHE: Disables firmware caching. Firmware caching is used to 26 * cache the firmware upon suspend, so that upon resume races against the 27 * firmware file lookup on storage is avoided. Used for calls where the 28 * file may be too big, or where the driver takes charge of its own 29 * firmware caching mechanism. 30 * @FW_OPT_NOFALLBACK: Disable the fallback mechanism. Takes precedence over 31 * &FW_OPT_UEVENT and &FW_OPT_USERHELPER. 32 */ 33 enum fw_opt { 34 FW_OPT_UEVENT = BIT(0), 35 FW_OPT_NOWAIT = BIT(1), 36 FW_OPT_USERHELPER = BIT(2), 37 FW_OPT_NO_WARN = BIT(3), 38 FW_OPT_NOCACHE = BIT(4), 39 FW_OPT_NOFALLBACK = BIT(5), 40 }; 41 42 enum fw_status { 43 FW_STATUS_UNKNOWN, 44 FW_STATUS_LOADING, 45 FW_STATUS_DONE, 46 FW_STATUS_ABORTED, 47 }; 48 49 /* 50 * Concurrent request_firmware() for the same firmware need to be 51 * serialized. struct fw_state is simple state machine which hold the 52 * state of the firmware loading. 53 */ 54 struct fw_state { 55 struct completion completion; 56 enum fw_status status; 57 }; 58 59 struct fw_priv { 60 struct kref ref; 61 struct list_head list; 62 struct firmware_cache *fwc; 63 struct fw_state fw_st; 64 void *data; 65 size_t size; 66 size_t allocated_size; 67 #ifdef CONFIG_FW_LOADER_PAGED_BUF 68 bool is_paged_buf; 69 struct page **pages; 70 int nr_pages; 71 int page_array_size; 72 #endif 73 #ifdef CONFIG_FW_LOADER_USER_HELPER 74 bool need_uevent; 75 struct list_head pending_list; 76 #endif 77 const char *fw_name; 78 }; 79 80 extern struct mutex fw_lock; 81 82 static inline bool __fw_state_check(struct fw_priv *fw_priv, 83 enum fw_status status) 84 { 85 struct fw_state *fw_st = &fw_priv->fw_st; 86 87 return fw_st->status == status; 88 } 89 90 static inline int __fw_state_wait_common(struct fw_priv *fw_priv, long timeout) 91 { 92 struct fw_state *fw_st = &fw_priv->fw_st; 93 long ret; 94 95 ret = wait_for_completion_killable_timeout(&fw_st->completion, timeout); 96 if (ret != 0 && fw_st->status == FW_STATUS_ABORTED) 97 return -ENOENT; 98 if (!ret) 99 return -ETIMEDOUT; 100 101 return ret < 0 ? ret : 0; 102 } 103 104 static inline void __fw_state_set(struct fw_priv *fw_priv, 105 enum fw_status status) 106 { 107 struct fw_state *fw_st = &fw_priv->fw_st; 108 109 WRITE_ONCE(fw_st->status, status); 110 111 if (status == FW_STATUS_DONE || status == FW_STATUS_ABORTED) 112 complete_all(&fw_st->completion); 113 } 114 115 static inline void fw_state_aborted(struct fw_priv *fw_priv) 116 { 117 __fw_state_set(fw_priv, FW_STATUS_ABORTED); 118 } 119 120 static inline bool fw_state_is_aborted(struct fw_priv *fw_priv) 121 { 122 return __fw_state_check(fw_priv, FW_STATUS_ABORTED); 123 } 124 125 static inline void fw_state_start(struct fw_priv *fw_priv) 126 { 127 __fw_state_set(fw_priv, FW_STATUS_LOADING); 128 } 129 130 static inline void fw_state_done(struct fw_priv *fw_priv) 131 { 132 __fw_state_set(fw_priv, FW_STATUS_DONE); 133 } 134 135 int assign_fw(struct firmware *fw, struct device *device, 136 enum fw_opt opt_flags); 137 138 #ifdef CONFIG_FW_LOADER_PAGED_BUF 139 void fw_free_paged_buf(struct fw_priv *fw_priv); 140 int fw_grow_paged_buf(struct fw_priv *fw_priv, int pages_needed); 141 int fw_map_paged_buf(struct fw_priv *fw_priv); 142 #else 143 static inline void fw_free_paged_buf(struct fw_priv *fw_priv) {} 144 int fw_grow_paged_buf(struct fw_priv *fw_priv, int pages_needed) { return -ENXIO; } 145 int fw_map_paged_buf(struct fw_priv *fw_priv) { return -ENXIO; } 146 #endif 147 148 #endif /* __FIRMWARE_LOADER_H */ 149