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