1 /* SPDX-License-Identifier: GPL-2.0 */ 2 #ifndef _LINUX_FIRMWARE_H 3 #define _LINUX_FIRMWARE_H 4 5 #include <linux/types.h> 6 #include <linux/compiler.h> 7 #include <linux/cleanup.h> 8 #include <linux/gfp.h> 9 10 #define FW_ACTION_NOUEVENT 0 11 #define FW_ACTION_UEVENT 1 12 13 struct firmware { 14 size_t size; 15 const u8 *data; 16 17 /* firmware loader private fields */ 18 void *priv; 19 }; 20 21 /** 22 * enum fw_upload_err - firmware upload error codes 23 * @FW_UPLOAD_ERR_NONE: returned to indicate success 24 * @FW_UPLOAD_ERR_HW_ERROR: error signalled by hardware, see kernel log 25 * @FW_UPLOAD_ERR_TIMEOUT: SW timed out on handshake with HW/firmware 26 * @FW_UPLOAD_ERR_CANCELED: upload was cancelled by the user 27 * @FW_UPLOAD_ERR_BUSY: there is an upload operation already in progress 28 * @FW_UPLOAD_ERR_INVALID_SIZE: invalid firmware image size 29 * @FW_UPLOAD_ERR_RW_ERROR: read or write to HW failed, see kernel log 30 * @FW_UPLOAD_ERR_WEAROUT: FLASH device is approaching wear-out, wait & retry 31 * @FW_UPLOAD_ERR_FW_INVALID: invalid firmware file 32 * @FW_UPLOAD_ERR_MAX: Maximum error code marker 33 */ 34 enum fw_upload_err { 35 FW_UPLOAD_ERR_NONE, 36 FW_UPLOAD_ERR_HW_ERROR, 37 FW_UPLOAD_ERR_TIMEOUT, 38 FW_UPLOAD_ERR_CANCELED, 39 FW_UPLOAD_ERR_BUSY, 40 FW_UPLOAD_ERR_INVALID_SIZE, 41 FW_UPLOAD_ERR_RW_ERROR, 42 FW_UPLOAD_ERR_WEAROUT, 43 FW_UPLOAD_ERR_FW_INVALID, 44 FW_UPLOAD_ERR_MAX 45 }; 46 47 struct fw_upload { 48 void *dd_handle; /* reference to parent driver */ 49 void *priv; /* firmware loader private fields */ 50 }; 51 52 /** 53 * struct fw_upload_ops - device specific operations to support firmware upload 54 * @prepare: Required: Prepare secure update 55 * @write: Required: The write() op receives the remaining 56 * size to be written and must return the actual 57 * size written or a negative error code. The write() 58 * op will be called repeatedly until all data is 59 * written. 60 * @poll_complete: Required: Check for the completion of the 61 * HW authentication/programming process. 62 * @cancel: Required: Request cancellation of update. This op 63 * is called from the context of a different kernel 64 * thread, so race conditions need to be considered. 65 * @cleanup: Optional: Complements the prepare() 66 * function and is called at the completion 67 * of the update, on success or failure, if the 68 * prepare function succeeded. 69 */ 70 struct fw_upload_ops { 71 enum fw_upload_err (*prepare)(struct fw_upload *fw_upload, 72 const u8 *data, u32 size); 73 enum fw_upload_err (*write)(struct fw_upload *fw_upload, 74 const u8 *data, u32 offset, 75 u32 size, u32 *written); 76 enum fw_upload_err (*poll_complete)(struct fw_upload *fw_upload); 77 void (*cancel)(struct fw_upload *fw_upload); 78 void (*cleanup)(struct fw_upload *fw_upload); 79 }; 80 81 struct module; 82 struct device; 83 84 /* 85 * Built-in firmware functionality is only available if FW_LOADER=y, but not 86 * FW_LOADER=m 87 */ 88 #ifdef CONFIG_FW_LOADER 89 bool firmware_request_builtin(struct firmware *fw, const char *name); 90 #else 91 static inline bool firmware_request_builtin(struct firmware *fw, 92 const char *name) 93 { 94 return false; 95 } 96 #endif 97 98 #if IS_REACHABLE(CONFIG_FW_LOADER) 99 int request_firmware(const struct firmware **fw, const char *name, 100 struct device *device); 101 int firmware_request_nowait_nowarn( 102 struct module *module, const char *name, 103 struct device *device, gfp_t gfp, void *context, 104 void (*cont)(const struct firmware *fw, void *context)); 105 int firmware_request_nowarn(const struct firmware **fw, const char *name, 106 struct device *device); 107 int firmware_request_platform(const struct firmware **fw, const char *name, 108 struct device *device); 109 int request_firmware_nowait( 110 struct module *module, bool uevent, 111 const char *name, struct device *device, gfp_t gfp, void *context, 112 void (*cont)(const struct firmware *fw, void *context)); 113 int request_firmware_direct(const struct firmware **fw, const char *name, 114 struct device *device); 115 int request_firmware_into_buf(const struct firmware **firmware_p, 116 const char *name, struct device *device, void *buf, size_t size); 117 int request_partial_firmware_into_buf(const struct firmware **firmware_p, 118 const char *name, struct device *device, 119 void *buf, size_t size, size_t offset); 120 121 void release_firmware(const struct firmware *fw); 122 #else 123 static inline int request_firmware(const struct firmware **fw, 124 const char *name, 125 struct device *device) 126 { 127 return -EINVAL; 128 } 129 130 static inline int firmware_request_nowait_nowarn( 131 struct module *module, const char *name, 132 struct device *device, gfp_t gfp, void *context, 133 void (*cont)(const struct firmware *fw, void *context)) 134 { 135 return -EINVAL; 136 } 137 138 static inline int firmware_request_nowarn(const struct firmware **fw, 139 const char *name, 140 struct device *device) 141 { 142 return -EINVAL; 143 } 144 145 static inline int firmware_request_platform(const struct firmware **fw, 146 const char *name, 147 struct device *device) 148 { 149 return -EINVAL; 150 } 151 152 static inline int request_firmware_nowait( 153 struct module *module, bool uevent, 154 const char *name, struct device *device, gfp_t gfp, void *context, 155 void (*cont)(const struct firmware *fw, void *context)) 156 { 157 return -EINVAL; 158 } 159 160 static inline void release_firmware(const struct firmware *fw) 161 { 162 } 163 164 static inline int request_firmware_direct(const struct firmware **fw, 165 const char *name, 166 struct device *device) 167 { 168 return -EINVAL; 169 } 170 171 static inline int request_firmware_into_buf(const struct firmware **firmware_p, 172 const char *name, struct device *device, void *buf, size_t size) 173 { 174 return -EINVAL; 175 } 176 177 static inline int request_partial_firmware_into_buf 178 (const struct firmware **firmware_p, 179 const char *name, 180 struct device *device, 181 void *buf, size_t size, size_t offset) 182 { 183 return -EINVAL; 184 } 185 186 #endif 187 188 #ifdef CONFIG_FW_UPLOAD 189 190 struct fw_upload * 191 firmware_upload_register(struct module *module, struct device *parent, 192 const char *name, const struct fw_upload_ops *ops, 193 void *dd_handle); 194 void firmware_upload_unregister(struct fw_upload *fw_upload); 195 196 #else 197 198 static inline struct fw_upload * 199 firmware_upload_register(struct module *module, struct device *parent, 200 const char *name, const struct fw_upload_ops *ops, 201 void *dd_handle) 202 { 203 return ERR_PTR(-EINVAL); 204 } 205 206 static inline void firmware_upload_unregister(struct fw_upload *fw_upload) 207 { 208 } 209 210 #endif 211 212 int firmware_request_cache(struct device *device, const char *name); 213 214 DEFINE_FREE(firmware, struct firmware *, release_firmware(_T)) 215 216 #endif 217