1/* SPDX-License-Identifier: GPL-2.0 */
  2#ifndef __FIRMWARE_LOADER_H
  3#define __FIRMWARE_LOADER_H
  4
  5#include <linux/firmware.h>
  6#include <linux/types.h>
  7#include <linux/kref.h>
  8#include <linux/list.h>
  9#include <linux/completion.h>
 10
 11#include <generated/utsrelease.h>
 12
 13/* firmware behavior options */
 14#define FW_OPT_UEVENT			(1U << 0)
 15#define FW_OPT_NOWAIT			(1U << 1)
 16#define FW_OPT_USERHELPER		(1U << 2)
 17#define FW_OPT_NO_WARN			(1U << 3)
 18#define FW_OPT_NOCACHE			(1U << 4)
 19#define FW_OPT_NOFALLBACK		(1U << 5)
 20
 21enum fw_status {
 22	FW_STATUS_UNKNOWN,
 23	FW_STATUS_LOADING,
 24	FW_STATUS_DONE,
 25	FW_STATUS_ABORTED,
 26};
 27
 28/*
 29 * Concurrent request_firmware() for the same firmware need to be
 30 * serialized.  struct fw_state is simple state machine which hold the
 31 * state of the firmware loading.
 32 */
 33struct fw_state {
 34	struct completion completion;
 35	enum fw_status status;
 36};
 37
 38struct fw_priv {
 39	struct kref ref;
 40	struct list_head list;
 41	struct firmware_cache *fwc;
 42	struct fw_state fw_st;
 43	void *data;
 44	size_t size;
 45	size_t allocated_size;
 46#ifdef CONFIG_FW_LOADER_USER_HELPER
 47	bool is_paged_buf;
 48	bool need_uevent;
 49	struct page **pages;
 50	int nr_pages;
 51	int page_array_size;
 52	struct list_head pending_list;
 53#endif
 54	const char *fw_name;
 55};
 56
 57extern struct mutex fw_lock;
 58
 59static inline bool __fw_state_check(struct fw_priv *fw_priv,
 60				    enum fw_status status)
 61{
 62	struct fw_state *fw_st = &fw_priv->fw_st;
 63
 64	return fw_st->status == status;
 65}
 66
 67static inline int __fw_state_wait_common(struct fw_priv *fw_priv, long timeout)
 68{
 69	struct fw_state *fw_st = &fw_priv->fw_st;
 70	long ret;
 71
 72	ret = wait_for_completion_killable_timeout(&fw_st->completion, timeout);
 73	if (ret != 0 && fw_st->status == FW_STATUS_ABORTED)
 74		return -ENOENT;
 75	if (!ret)
 76		return -ETIMEDOUT;
 77
 78	return ret < 0 ? ret : 0;
 79}
 80
 81static inline void __fw_state_set(struct fw_priv *fw_priv,
 82				  enum fw_status status)
 83{
 84	struct fw_state *fw_st = &fw_priv->fw_st;
 85
 86	WRITE_ONCE(fw_st->status, status);
 87
 88	if (status == FW_STATUS_DONE || status == FW_STATUS_ABORTED)
 89		complete_all(&fw_st->completion);
 90}
 91
 92static inline void fw_state_aborted(struct fw_priv *fw_priv)
 93{
 94	__fw_state_set(fw_priv, FW_STATUS_ABORTED);
 95}
 96
 97static inline bool fw_state_is_aborted(struct fw_priv *fw_priv)
 98{
 99	return __fw_state_check(fw_priv, FW_STATUS_ABORTED);
100}
101
102static inline void fw_state_start(struct fw_priv *fw_priv)
103{
104	__fw_state_set(fw_priv, FW_STATUS_LOADING);
105}
106
107static inline void fw_state_done(struct fw_priv *fw_priv)
108{
109	__fw_state_set(fw_priv, FW_STATUS_DONE);
110}
111
112int assign_fw(struct firmware *fw, struct device *device,
113	      unsigned int opt_flags);
114
115#endif /* __FIRMWARE_LOADER_H */