drivers/usb/gadget/function/u_fs.h

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