xref: /linux/drivers/usb/gadget/function/u_fs.h (revision 1ac731c529cd4d6adbce134754b51ff7d822b145)
1 /* SPDX-License-Identifier: GPL-2.0 */
2 /*
3  * u_fs.h
4  *
5  * Utility definitions for the FunctionFS
6  *
7  * Copyright (c) 2013 Samsung Electronics Co., Ltd.
8  *		http://www.samsung.com
9  *
10  * Author: Andrzej Pietrasiewicz <andrzejtp2010@gmail.com>
11  */
12 
13 #ifndef U_FFS_H
14 #define U_FFS_H
15 
16 #include <linux/usb/composite.h>
17 #include <linux/list.h>
18 #include <linux/mutex.h>
19 #include <linux/workqueue.h>
20 #include <linux/refcount.h>
21 
22 #ifdef VERBOSE_DEBUG
23 #ifndef pr_vdebug
24 #  define pr_vdebug pr_debug
25 #endif /* pr_vdebug */
26 #  define ffs_dump_mem(prefix, ptr, len) \
27 	print_hex_dump_bytes(pr_fmt(prefix ": "), DUMP_PREFIX_NONE, ptr, len)
28 #else
29 #ifndef pr_vdebug
30 #  define pr_vdebug(...)                 do { } while (0)
31 #endif /* pr_vdebug */
32 #  define ffs_dump_mem(prefix, ptr, len) do { } while (0)
33 #endif /* VERBOSE_DEBUG */
34 
35 struct f_fs_opts;
36 
37 struct ffs_dev {
38 	struct ffs_data *ffs_data;
39 	struct f_fs_opts *opts;
40 	struct list_head entry;
41 
42 	char name[41];
43 
44 	bool mounted;
45 	bool desc_ready;
46 	bool single;
47 
48 	int (*ffs_ready_callback)(struct ffs_data *ffs);
49 	void (*ffs_closed_callback)(struct ffs_data *ffs);
50 	void *(*ffs_acquire_dev_callback)(struct ffs_dev *dev);
51 	void (*ffs_release_dev_callback)(struct ffs_dev *dev);
52 };
53 
54 extern struct mutex ffs_lock;
55 
ffs_dev_lock(void)56 static inline void ffs_dev_lock(void)
57 {
58 	mutex_lock(&ffs_lock);
59 }
60 
ffs_dev_unlock(void)61 static inline void ffs_dev_unlock(void)
62 {
63 	mutex_unlock(&ffs_lock);
64 }
65 
66 int ffs_name_dev(struct ffs_dev *dev, const char *name);
67 int ffs_single_dev(struct ffs_dev *dev);
68 
69 struct ffs_epfile;
70 struct ffs_function;
71 
72 enum ffs_state {
73 	/*
74 	 * Waiting for descriptors and strings.
75 	 *
76 	 * In this state no open(2), read(2) or write(2) on epfiles
77 	 * may succeed (which should not be the problem as there
78 	 * should be no such files opened in the first place).
79 	 */
80 	FFS_READ_DESCRIPTORS,
81 	FFS_READ_STRINGS,
82 
83 	/*
84 	 * We've got descriptors and strings.  We are or have called
85 	 * functionfs_ready_callback().  functionfs_bind() may have
86 	 * been called but we don't know.
87 	 *
88 	 * This is the only state in which operations on epfiles may
89 	 * succeed.
90 	 */
91 	FFS_ACTIVE,
92 
93 	/*
94 	 * Function is visible to host, but it's not functional. All
95 	 * setup requests are stalled and transfers on another endpoints
96 	 * are refused. All epfiles, except ep0, are deleted so there
97 	 * is no way to perform any operations on them.
98 	 *
99 	 * This state is set after closing all functionfs files, when
100 	 * mount parameter "no_disconnect=1" has been set. Function will
101 	 * remain in deactivated state until filesystem is umounted or
102 	 * ep0 is opened again. In the second case functionfs state will
103 	 * be reset, and it will be ready for descriptors and strings
104 	 * writing.
105 	 *
106 	 * This is useful only when functionfs is composed to gadget
107 	 * with another function which can perform some critical
108 	 * operations, and it's strongly desired to have this operations
109 	 * completed, even after functionfs files closure.
110 	 */
111 	FFS_DEACTIVATED,
112 
113 	/*
114 	 * All endpoints have been closed.  This state is also set if
115 	 * we encounter an unrecoverable error.  The only
116 	 * unrecoverable error is situation when after reading strings
117 	 * from user space we fail to initialise epfiles or
118 	 * functionfs_ready_callback() returns with error (<0).
119 	 *
120 	 * In this state no open(2), read(2) or write(2) (both on ep0
121 	 * as well as epfile) may succeed (at this point epfiles are
122 	 * unlinked and all closed so this is not a problem; ep0 is
123 	 * also closed but ep0 file exists and so open(2) on ep0 must
124 	 * fail).
125 	 */
126 	FFS_CLOSING
127 };
128 
129 enum ffs_setup_state {
130 	/* There is no setup request pending. */
131 	FFS_NO_SETUP,
132 	/*
133 	 * User has read events and there was a setup request event
134 	 * there.  The next read/write on ep0 will handle the
135 	 * request.
136 	 */
137 	FFS_SETUP_PENDING,
138 	/*
139 	 * There was event pending but before user space handled it
140 	 * some other event was introduced which canceled existing
141 	 * setup.  If this state is set read/write on ep0 return
142 	 * -EIDRM.  This state is only set when adding event.
143 	 */
144 	FFS_SETUP_CANCELLED
145 };
146 
147 struct ffs_data {
148 	struct usb_gadget		*gadget;
149 
150 	/*
151 	 * Protect access read/write operations, only one read/write
152 	 * at a time.  As a consequence protects ep0req and company.
153 	 * While setup request is being processed (queued) this is
154 	 * held.
155 	 */
156 	struct mutex			mutex;
157 
158 	/*
159 	 * Protect access to endpoint related structures (basically
160 	 * usb_ep_queue(), usb_ep_dequeue(), etc. calls) except for
161 	 * endpoint zero.
162 	 */
163 	spinlock_t			eps_lock;
164 
165 	/*
166 	 * XXX REVISIT do we need our own request? Since we are not
167 	 * handling setup requests immediately user space may be so
168 	 * slow that another setup will be sent to the gadget but this
169 	 * time not to us but another function and then there could be
170 	 * a race.  Is that the case? Or maybe we can use cdev->req
171 	 * after all, maybe we just need some spinlock for that?
172 	 */
173 	struct usb_request		*ep0req;		/* P: mutex */
174 	struct completion		ep0req_completion;	/* P: mutex */
175 
176 	/* reference counter */
177 	refcount_t			ref;
178 	/* how many files are opened (EP0 and others) */
179 	atomic_t			opened;
180 
181 	/* EP0 state */
182 	enum ffs_state			state;
183 
184 	/*
185 	 * Possible transitions:
186 	 * + FFS_NO_SETUP        -> FFS_SETUP_PENDING  -- P: ev.waitq.lock
187 	 *               happens only in ep0 read which is P: mutex
188 	 * + FFS_SETUP_PENDING   -> FFS_NO_SETUP       -- P: ev.waitq.lock
189 	 *               happens only in ep0 i/o  which is P: mutex
190 	 * + FFS_SETUP_PENDING   -> FFS_SETUP_CANCELLED -- P: ev.waitq.lock
191 	 * + FFS_SETUP_CANCELLED -> FFS_NO_SETUP        -- cmpxchg
192 	 *
193 	 * This field should never be accessed directly and instead
194 	 * ffs_setup_state_clear_cancelled function should be used.
195 	 */
196 	enum ffs_setup_state		setup_state;
197 
198 	/* Events & such. */
199 	struct {
200 		u8				types[4];
201 		unsigned short			count;
202 		/* XXX REVISIT need to update it in some places, or do we? */
203 		unsigned short			can_stall;
204 		struct usb_ctrlrequest		setup;
205 
206 		wait_queue_head_t		waitq;
207 	} ev; /* the whole structure, P: ev.waitq.lock */
208 
209 	/* Flags */
210 	unsigned long			flags;
211 #define FFS_FL_CALL_CLOSED_CALLBACK 0
212 #define FFS_FL_BOUND                1
213 
214 	/* For waking up blocked threads when function is enabled. */
215 	wait_queue_head_t		wait;
216 
217 	/* Active function */
218 	struct ffs_function		*func;
219 
220 	/*
221 	 * Device name, write once when file system is mounted.
222 	 * Intended for user to read if she wants.
223 	 */
224 	const char			*dev_name;
225 	/* Private data for our user (ie. gadget).  Managed by user. */
226 	void				*private_data;
227 
228 	/* filled by __ffs_data_got_descs() */
229 	/*
230 	 * raw_descs is what you kfree, real_descs points inside of raw_descs,
231 	 * where full speed, high speed and super speed descriptors start.
232 	 * real_descs_length is the length of all those descriptors.
233 	 */
234 	const void			*raw_descs_data;
235 	const void			*raw_descs;
236 	unsigned			raw_descs_length;
237 	unsigned			fs_descs_count;
238 	unsigned			hs_descs_count;
239 	unsigned			ss_descs_count;
240 	unsigned			ms_os_descs_count;
241 	unsigned			ms_os_descs_ext_prop_count;
242 	unsigned			ms_os_descs_ext_prop_name_len;
243 	unsigned			ms_os_descs_ext_prop_data_len;
244 	void				*ms_os_descs_ext_prop_avail;
245 	void				*ms_os_descs_ext_prop_name_avail;
246 	void				*ms_os_descs_ext_prop_data_avail;
247 
248 	unsigned			user_flags;
249 
250 #define FFS_MAX_EPS_COUNT 31
251 	u8				eps_addrmap[FFS_MAX_EPS_COUNT];
252 
253 	unsigned short			strings_count;
254 	unsigned short			interfaces_count;
255 	unsigned short			eps_count;
256 	unsigned short			_pad1;
257 
258 	/* filled by __ffs_data_got_strings() */
259 	/* ids in stringtabs are set in functionfs_bind() */
260 	const void			*raw_strings;
261 	struct usb_gadget_strings	**stringtabs;
262 
263 	/*
264 	 * File system's super block, write once when file system is
265 	 * mounted.
266 	 */
267 	struct super_block		*sb;
268 
269 	/* File permissions, written once when fs is mounted */
270 	struct ffs_file_perms {
271 		umode_t				mode;
272 		kuid_t				uid;
273 		kgid_t				gid;
274 	}				file_perms;
275 
276 	struct eventfd_ctx *ffs_eventfd;
277 	struct workqueue_struct *io_completion_wq;
278 	bool no_disconnect;
279 	struct work_struct reset_work;
280 
281 	/*
282 	 * The endpoint files, filled by ffs_epfiles_create(),
283 	 * destroyed by ffs_epfiles_destroy().
284 	 */
285 	struct ffs_epfile		*epfiles;
286 };
287 
288 
289 struct f_fs_opts {
290 	struct usb_function_instance	func_inst;
291 	struct ffs_dev			*dev;
292 	unsigned			refcnt;
293 	bool				no_configfs;
294 };
295 
to_f_fs_opts(struct usb_function_instance * fi)296 static inline struct f_fs_opts *to_f_fs_opts(struct usb_function_instance *fi)
297 {
298 	return container_of(fi, struct f_fs_opts, func_inst);
299 }
300 
301 #endif /* U_FFS_H */
302