1 /* SPDX-License-Identifier: GPL-2.0 */
2 #ifndef _LINUX_FIRMWARE_H
3 #define _LINUX_FIRMWARE_H
5 #include <linux/types.h>
6 #include <linux/compiler.h>
9 #define FW_ACTION_NOUEVENT 0
10 #define FW_ACTION_UEVENT 1
16 /* firmware loader private fields */
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
35 FW_UPLOAD_ERR_HW_ERROR,
36 FW_UPLOAD_ERR_TIMEOUT,
37 FW_UPLOAD_ERR_CANCELED,
39 FW_UPLOAD_ERR_INVALID_SIZE,
40 FW_UPLOAD_ERR_RW_ERROR,
41 FW_UPLOAD_ERR_WEAROUT,
42 FW_UPLOAD_ERR_FW_INVALID,
47 void *dd_handle; /* reference to parent driver */
48 void *priv; /* firmware loader private fields */
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
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.
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);
84 * Built-in firmware functionality is only available if FW_LOADER=y, but not
87 #ifdef CONFIG_FW_LOADER
88 bool firmware_request_builtin(struct firmware *fw, const char *name);
90 static inline bool firmware_request_builtin(struct firmware *fw,
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);
116 void release_firmware(const struct firmware *fw);
118 static inline int request_firmware(const struct firmware **fw,
120 struct device *device)
125 static inline int firmware_request_nowarn(const struct firmware **fw,
127 struct device *device)
132 static inline int firmware_request_platform(const struct firmware **fw,
134 struct device *device)
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))
147 static inline void release_firmware(const struct firmware *fw)
151 static inline int request_firmware_direct(const struct firmware **fw,
153 struct device *device)
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)
164 static inline int request_partial_firmware_into_buf
165 (const struct firmware **firmware_p,
167 struct device *device,
168 void *buf, size_t size, size_t offset)
175 #ifdef CONFIG_FW_UPLOAD
178 firmware_upload_register(struct module *module, struct device *parent,
179 const char *name, const struct fw_upload_ops *ops,
181 void firmware_upload_unregister(struct fw_upload *fw_upload);
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,
190 return ERR_PTR(-EINVAL);
193 static inline void firmware_upload_unregister(struct fw_upload *fw_upload)
199 int firmware_request_cache(struct device *device, const char *name);