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 
21 enum 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  */
33 struct fw_state {
34 	struct completion completion;
35 	enum fw_status status;
36 };
37 
38 struct 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 
57 extern struct mutex fw_lock;
58 
59 static 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 
67 static 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 
81 static 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 
92 static inline void fw_state_aborted(struct fw_priv *fw_priv)
93 {
94 	__fw_state_set(fw_priv, FW_STATUS_ABORTED);
95 }
96 
97 static inline bool fw_state_is_aborted(struct fw_priv *fw_priv)
98 {
99 	return __fw_state_check(fw_priv, FW_STATUS_ABORTED);
100 }
101 
102 static inline void fw_state_start(struct fw_priv *fw_priv)
103 {
104 	__fw_state_set(fw_priv, FW_STATUS_LOADING);
105 }
106 
107 static inline void fw_state_done(struct fw_priv *fw_priv)
108 {
109 	__fw_state_set(fw_priv, FW_STATUS_DONE);
110 }
111 
112 int assign_fw(struct firmware *fw, struct device *device,
113 	      unsigned int opt_flags);
114 
115 #endif /* __FIRMWARE_LOADER_H */
116