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
firmware_request_builtin(struct firmware * fw,const char * name)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
request_firmware(const struct firmware ** fw,const char * name,struct device * device)123 static inline int request_firmware(const struct firmware **fw,
124 const char *name,
125 struct device *device)
126 {
127 return -EINVAL;
128 }
129
firmware_request_nowait_nowarn(struct module * module,const char * name,struct device * device,gfp_t gfp,void * context,void (* cont)(const struct firmware * fw,void * context))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
firmware_request_nowarn(const struct firmware ** fw,const char * name,struct device * device)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
firmware_request_platform(const struct firmware ** fw,const char * name,struct device * device)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
request_firmware_nowait(struct module * module,bool uevent,const char * name,struct device * device,gfp_t gfp,void * context,void (* cont)(const struct firmware * fw,void * context))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
release_firmware(const struct firmware * fw)160 static inline void release_firmware(const struct firmware *fw)
161 {
162 }
163
request_firmware_direct(const struct firmware ** fw,const char * name,struct device * device)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
request_firmware_into_buf(const struct firmware ** firmware_p,const char * name,struct device * device,void * buf,size_t size)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
request_partial_firmware_into_buf(const struct firmware ** firmware_p,const char * name,struct device * device,void * buf,size_t size,size_t offset)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 *
firmware_upload_register(struct module * module,struct device * parent,const char * name,const struct fw_upload_ops * ops,void * dd_handle)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
firmware_upload_unregister(struct fw_upload * fw_upload)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