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
13struct 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 */
34enum 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
47struct 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 */
70struct 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
81struct module;
82struct 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
89bool firmware_request_builtin(struct firmware *fw, const char *name);
90#else
91static 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)
99int request_firmware(const struct firmware **fw, const char *name,
100		     struct device *device);
101int firmware_request_nowarn(const struct firmware **fw, const char *name,
102			    struct device *device);
103int firmware_request_platform(const struct firmware **fw, const char *name,
104			      struct device *device);
105int request_firmware_nowait(
106	struct module *module, bool uevent,
107	const char *name, struct device *device, gfp_t gfp, void *context,
108	void (*cont)(const struct firmware *fw, void *context));
109int request_firmware_direct(const struct firmware **fw, const char *name,
110			    struct device *device);
111int request_firmware_into_buf(const struct firmware **firmware_p,
112	const char *name, struct device *device, void *buf, size_t size);
113int request_partial_firmware_into_buf(const struct firmware **firmware_p,
114				      const char *name, struct device *device,
115				      void *buf, size_t size, size_t offset);
116
117void release_firmware(const struct firmware *fw);
118#else
119static inline int request_firmware(const struct firmware **fw,
120				   const char *name,
121				   struct device *device)
122{
123	return -EINVAL;
124}
125
126static inline int firmware_request_nowarn(const struct firmware **fw,
127					  const char *name,
128					  struct device *device)
129{
130	return -EINVAL;
131}
132
133static inline int firmware_request_platform(const struct firmware **fw,
134					    const char *name,
135					    struct device *device)
136{
137	return -EINVAL;
138}
139
140static inline int request_firmware_nowait(
141	struct module *module, bool uevent,
142	const char *name, struct device *device, gfp_t gfp, void *context,
143	void (*cont)(const struct firmware *fw, void *context))
144{
145	return -EINVAL;
146}
147
148static inline void release_firmware(const struct firmware *fw)
149{
150}
151
152static inline int request_firmware_direct(const struct firmware **fw,
153					  const char *name,
154					  struct device *device)
155{
156	return -EINVAL;
157}
158
159static inline int request_firmware_into_buf(const struct firmware **firmware_p,
160	const char *name, struct device *device, void *buf, size_t size)
161{
162	return -EINVAL;
163}
164
165static inline int request_partial_firmware_into_buf
166					(const struct firmware **firmware_p,
167					 const char *name,
168					 struct device *device,
169					 void *buf, size_t size, size_t offset)
170{
171	return -EINVAL;
172}
173
174#endif
175
176#ifdef CONFIG_FW_UPLOAD
177
178struct fw_upload *
179firmware_upload_register(struct module *module, struct device *parent,
180			 const char *name, const struct fw_upload_ops *ops,
181			 void *dd_handle);
182void firmware_upload_unregister(struct fw_upload *fw_upload);
183
184#else
185
186static inline struct fw_upload *
187firmware_upload_register(struct module *module, struct device *parent,
188			 const char *name, const struct fw_upload_ops *ops,
189			 void *dd_handle)
190{
191		return ERR_PTR(-EINVAL);
192}
193
194static inline void firmware_upload_unregister(struct fw_upload *fw_upload)
195{
196}
197
198#endif
199
200int firmware_request_cache(struct device *device, const char *name);
201
202DEFINE_FREE(firmware, struct firmware *, release_firmware(_T))
203
204#endif
205