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