drivers/usb/gadget/function/u_fs.h

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