firmware.h

  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_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));
105int firmware_request_nowarn(const struct firmware **fw, const char *name,
106			    struct device *device);
107int firmware_request_platform(const struct firmware **fw, const char *name,
108			      struct device *device);
109int 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));
113int request_firmware_direct(const struct firmware **fw, const char *name,
114			    struct device *device);
115int request_firmware_into_buf(const struct firmware **firmware_p,
116	const char *name, struct device *device, void *buf, size_t size);
117int 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
121void release_firmware(const struct firmware *fw);
122#else
123static inline int request_firmware(const struct firmware **fw,
124				   const char *name,
125				   struct device *device)
126{
127	return -EINVAL;
128}
129
130static 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
138static inline int firmware_request_nowarn(const struct firmware **fw,
139					  const char *name,
140					  struct device *device)
141{
142	return -EINVAL;
143}
144
145static inline int firmware_request_platform(const struct firmware **fw,
146					    const char *name,
147					    struct device *device)
148{
149	return -EINVAL;
150}
151
152static 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
160static inline void release_firmware(const struct firmware *fw)
161{
162}
163
164static inline int request_firmware_direct(const struct firmware **fw,
165					  const char *name,
166					  struct device *device)
167{
168	return -EINVAL;
169}
170
171static 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
177static 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
190struct fw_upload *
191firmware_upload_register(struct module *module, struct device *parent,
192			 const char *name, const struct fw_upload_ops *ops,
193			 void *dd_handle);
194void firmware_upload_unregister(struct fw_upload *fw_upload);
195
196#else
197
198static inline struct fw_upload *
199firmware_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
206static inline void firmware_upload_unregister(struct fw_upload *fw_upload)
207{
208}
209
210#endif
211
212int firmware_request_cache(struct device *device, const char *name);
213
214DEFINE_FREE(firmware, struct firmware *, release_firmware(_T))
215
216#endif