]> git.karo-electronics.de Git - karo-tx-linux.git/blob - include/linux/usb/composite.h
Merge branch 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab...
[karo-tx-linux.git] / include / linux / usb / composite.h
1 /*
2  * composite.h -- framework for usb gadgets which are composite devices
3  *
4  * Copyright (C) 2006-2008 David Brownell
5  *
6  * This program is free software; you can redistribute it and/or modify
7  * it under the terms of the GNU General Public License as published by
8  * the Free Software Foundation; either version 2 of the License, or
9  * (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
19  */
20
21 #ifndef __LINUX_USB_COMPOSITE_H
22 #define __LINUX_USB_COMPOSITE_H
23
24 /*
25  * This framework is an optional layer on top of the USB Gadget interface,
26  * making it easier to build (a) Composite devices, supporting multiple
27  * functions within any single configuration, and (b) Multi-configuration
28  * devices, also supporting multiple functions but without necessarily
29  * having more than one function per configuration.
30  *
31  * Example:  a device with a single configuration supporting both network
32  * link and mass storage functions is a composite device.  Those functions
33  * might alternatively be packaged in individual configurations, but in
34  * the composite model the host can use both functions at the same time.
35  */
36
37 #include <linux/bcd.h>
38 #include <linux/version.h>
39 #include <linux/usb/ch9.h>
40 #include <linux/usb/gadget.h>
41 #include <linux/log2.h>
42 #include <linux/configfs.h>
43
44 /*
45  * USB function drivers should return USB_GADGET_DELAYED_STATUS if they
46  * wish to delay the data/status stages of the control transfer till they
47  * are ready. The control transfer will then be kept from completing till
48  * all the function drivers that requested for USB_GADGET_DELAYED_STAUS
49  * invoke usb_composite_setup_continue().
50  */
51 #define USB_GADGET_DELAYED_STATUS       0x7fff  /* Impossibly large value */
52
53 /* big enough to hold our biggest descriptor */
54 #define USB_COMP_EP0_BUFSIZ     1024
55
56 #define USB_MS_TO_HS_INTERVAL(x)        (ilog2((x * 1000 / 125)) + 1)
57 struct usb_configuration;
58
59 /**
60  * struct usb_function - describes one function of a configuration
61  * @name: For diagnostics, identifies the function.
62  * @strings: tables of strings, keyed by identifiers assigned during bind()
63  *      and by language IDs provided in control requests
64  * @fs_descriptors: Table of full (or low) speed descriptors, using interface and
65  *      string identifiers assigned during @bind().  If this pointer is null,
66  *      the function will not be available at full speed (or at low speed).
67  * @hs_descriptors: Table of high speed descriptors, using interface and
68  *      string identifiers assigned during @bind().  If this pointer is null,
69  *      the function will not be available at high speed.
70  * @ss_descriptors: Table of super speed descriptors, using interface and
71  *      string identifiers assigned during @bind(). If this
72  *      pointer is null after initiation, the function will not
73  *      be available at super speed.
74  * @config: assigned when @usb_add_function() is called; this is the
75  *      configuration with which this function is associated.
76  * @bind: Before the gadget can register, all of its functions bind() to the
77  *      available resources including string and interface identifiers used
78  *      in interface or class descriptors; endpoints; I/O buffers; and so on.
79  * @unbind: Reverses @bind; called as a side effect of unregistering the
80  *      driver which added this function.
81  * @free_func: free the struct usb_function.
82  * @mod: (internal) points to the module that created this structure.
83  * @set_alt: (REQUIRED) Reconfigures altsettings; function drivers may
84  *      initialize usb_ep.driver data at this time (when it is used).
85  *      Note that setting an interface to its current altsetting resets
86  *      interface state, and that all interfaces have a disabled state.
87  * @get_alt: Returns the active altsetting.  If this is not provided,
88  *      then only altsetting zero is supported.
89  * @disable: (REQUIRED) Indicates the function should be disabled.  Reasons
90  *      include host resetting or reconfiguring the gadget, and disconnection.
91  * @setup: Used for interface-specific control requests.
92  * @suspend: Notifies functions when the host stops sending USB traffic.
93  * @resume: Notifies functions when the host restarts USB traffic.
94  * @get_status: Returns function status as a reply to
95  *      GetStatus() request when the recepient is Interface.
96  * @func_suspend: callback to be called when
97  *      SetFeature(FUNCTION_SUSPEND) is reseived
98  *
99  * A single USB function uses one or more interfaces, and should in most
100  * cases support operation at both full and high speeds.  Each function is
101  * associated by @usb_add_function() with a one configuration; that function
102  * causes @bind() to be called so resources can be allocated as part of
103  * setting up a gadget driver.  Those resources include endpoints, which
104  * should be allocated using @usb_ep_autoconfig().
105  *
106  * To support dual speed operation, a function driver provides descriptors
107  * for both high and full speed operation.  Except in rare cases that don't
108  * involve bulk endpoints, each speed needs different endpoint descriptors.
109  *
110  * Function drivers choose their own strategies for managing instance data.
111  * The simplest strategy just declares it "static', which means the function
112  * can only be activated once.  If the function needs to be exposed in more
113  * than one configuration at a given speed, it needs to support multiple
114  * usb_function structures (one for each configuration).
115  *
116  * A more complex strategy might encapsulate a @usb_function structure inside
117  * a driver-specific instance structure to allows multiple activations.  An
118  * example of multiple activations might be a CDC ACM function that supports
119  * two or more distinct instances within the same configuration, providing
120  * several independent logical data links to a USB host.
121  */
122
123 struct usb_function {
124         const char                      *name;
125         struct usb_gadget_strings       **strings;
126         struct usb_descriptor_header    **fs_descriptors;
127         struct usb_descriptor_header    **hs_descriptors;
128         struct usb_descriptor_header    **ss_descriptors;
129
130         struct usb_configuration        *config;
131
132         /* REVISIT:  bind() functions can be marked __init, which
133          * makes trouble for section mismatch analysis.  See if
134          * we can't restructure things to avoid mismatching.
135          * Related:  unbind() may kfree() but bind() won't...
136          */
137
138         /* configuration management:  bind/unbind */
139         int                     (*bind)(struct usb_configuration *,
140                                         struct usb_function *);
141         void                    (*unbind)(struct usb_configuration *,
142                                         struct usb_function *);
143         void                    (*free_func)(struct usb_function *f);
144         struct module           *mod;
145
146         /* runtime state management */
147         int                     (*set_alt)(struct usb_function *,
148                                         unsigned interface, unsigned alt);
149         int                     (*get_alt)(struct usb_function *,
150                                         unsigned interface);
151         void                    (*disable)(struct usb_function *);
152         int                     (*setup)(struct usb_function *,
153                                         const struct usb_ctrlrequest *);
154         void                    (*suspend)(struct usb_function *);
155         void                    (*resume)(struct usb_function *);
156
157         /* USB 3.0 additions */
158         int                     (*get_status)(struct usb_function *);
159         int                     (*func_suspend)(struct usb_function *,
160                                                 u8 suspend_opt);
161         /* private: */
162         /* internals */
163         struct list_head                list;
164         DECLARE_BITMAP(endpoints, 32);
165         const struct usb_function_instance *fi;
166 };
167
168 int usb_add_function(struct usb_configuration *, struct usb_function *);
169
170 int usb_function_deactivate(struct usb_function *);
171 int usb_function_activate(struct usb_function *);
172
173 int usb_interface_id(struct usb_configuration *, struct usb_function *);
174
175 int config_ep_by_speed(struct usb_gadget *g, struct usb_function *f,
176                         struct usb_ep *_ep);
177
178 #define MAX_CONFIG_INTERFACES           16      /* arbitrary; max 255 */
179
180 /**
181  * struct usb_configuration - represents one gadget configuration
182  * @label: For diagnostics, describes the configuration.
183  * @strings: Tables of strings, keyed by identifiers assigned during @bind()
184  *      and by language IDs provided in control requests.
185  * @descriptors: Table of descriptors preceding all function descriptors.
186  *      Examples include OTG and vendor-specific descriptors.
187  * @unbind: Reverses @bind; called as a side effect of unregistering the
188  *      driver which added this configuration.
189  * @setup: Used to delegate control requests that aren't handled by standard
190  *      device infrastructure or directed at a specific interface.
191  * @bConfigurationValue: Copied into configuration descriptor.
192  * @iConfiguration: Copied into configuration descriptor.
193  * @bmAttributes: Copied into configuration descriptor.
194  * @MaxPower: Power consumtion in mA. Used to compute bMaxPower in the
195  *      configuration descriptor after considering the bus speed.
196  * @cdev: assigned by @usb_add_config() before calling @bind(); this is
197  *      the device associated with this configuration.
198  *
199  * Configurations are building blocks for gadget drivers structured around
200  * function drivers.  Simple USB gadgets require only one function and one
201  * configuration, and handle dual-speed hardware by always providing the same
202  * functionality.  Slightly more complex gadgets may have more than one
203  * single-function configuration at a given speed; or have configurations
204  * that only work at one speed.
205  *
206  * Composite devices are, by definition, ones with configurations which
207  * include more than one function.
208  *
209  * The lifecycle of a usb_configuration includes allocation, initialization
210  * of the fields described above, and calling @usb_add_config() to set up
211  * internal data and bind it to a specific device.  The configuration's
212  * @bind() method is then used to initialize all the functions and then
213  * call @usb_add_function() for them.
214  *
215  * Those functions would normally be independent of each other, but that's
216  * not mandatory.  CDC WMC devices are an example where functions often
217  * depend on other functions, with some functions subsidiary to others.
218  * Such interdependency may be managed in any way, so long as all of the
219  * descriptors complete by the time the composite driver returns from
220  * its bind() routine.
221  */
222 struct usb_configuration {
223         const char                      *label;
224         struct usb_gadget_strings       **strings;
225         const struct usb_descriptor_header **descriptors;
226
227         /* REVISIT:  bind() functions can be marked __init, which
228          * makes trouble for section mismatch analysis.  See if
229          * we can't restructure things to avoid mismatching...
230          */
231
232         /* configuration management: unbind/setup */
233         void                    (*unbind)(struct usb_configuration *);
234         int                     (*setup)(struct usb_configuration *,
235                                         const struct usb_ctrlrequest *);
236
237         /* fields in the config descriptor */
238         u8                      bConfigurationValue;
239         u8                      iConfiguration;
240         u8                      bmAttributes;
241         u16                     MaxPower;
242
243         struct usb_composite_dev        *cdev;
244
245         /* private: */
246         /* internals */
247         struct list_head        list;
248         struct list_head        functions;
249         u8                      next_interface_id;
250         unsigned                superspeed:1;
251         unsigned                highspeed:1;
252         unsigned                fullspeed:1;
253         struct usb_function     *interface[MAX_CONFIG_INTERFACES];
254 };
255
256 int usb_add_config(struct usb_composite_dev *,
257                 struct usb_configuration *,
258                 int (*)(struct usb_configuration *));
259
260 void usb_remove_config(struct usb_composite_dev *,
261                 struct usb_configuration *);
262
263 /* predefined index for usb_composite_driver */
264 enum {
265         USB_GADGET_MANUFACTURER_IDX     = 0,
266         USB_GADGET_PRODUCT_IDX,
267         USB_GADGET_SERIAL_IDX,
268         USB_GADGET_FIRST_AVAIL_IDX,
269 };
270
271 /**
272  * struct usb_composite_driver - groups configurations into a gadget
273  * @name: For diagnostics, identifies the driver.
274  * @dev: Template descriptor for the device, including default device
275  *      identifiers.
276  * @strings: tables of strings, keyed by identifiers assigned during @bind
277  *      and language IDs provided in control requests. Note: The first entries
278  *      are predefined. The first entry that may be used is
279  *      USB_GADGET_FIRST_AVAIL_IDX
280  * @max_speed: Highest speed the driver supports.
281  * @needs_serial: set to 1 if the gadget needs userspace to provide
282  *      a serial number.  If one is not provided, warning will be printed.
283  * @bind: (REQUIRED) Used to allocate resources that are shared across the
284  *      whole device, such as string IDs, and add its configurations using
285  *      @usb_add_config(). This may fail by returning a negative errno
286  *      value; it should return zero on successful initialization.
287  * @unbind: Reverses @bind; called as a side effect of unregistering
288  *      this driver.
289  * @disconnect: optional driver disconnect method
290  * @suspend: Notifies when the host stops sending USB traffic,
291  *      after function notifications
292  * @resume: Notifies configuration when the host restarts USB traffic,
293  *      before function notifications
294  * @gadget_driver: Gadget driver controlling this driver
295  *
296  * Devices default to reporting self powered operation.  Devices which rely
297  * on bus powered operation should report this in their @bind method.
298  *
299  * Before returning from @bind, various fields in the template descriptor
300  * may be overridden.  These include the idVendor/idProduct/bcdDevice values
301  * normally to bind the appropriate host side driver, and the three strings
302  * (iManufacturer, iProduct, iSerialNumber) normally used to provide user
303  * meaningful device identifiers.  (The strings will not be defined unless
304  * they are defined in @dev and @strings.)  The correct ep0 maxpacket size
305  * is also reported, as defined by the underlying controller driver.
306  */
307 struct usb_composite_driver {
308         const char                              *name;
309         const struct usb_device_descriptor      *dev;
310         struct usb_gadget_strings               **strings;
311         enum usb_device_speed                   max_speed;
312         unsigned                needs_serial:1;
313
314         int                     (*bind)(struct usb_composite_dev *cdev);
315         int                     (*unbind)(struct usb_composite_dev *);
316
317         void                    (*disconnect)(struct usb_composite_dev *);
318
319         /* global suspend hooks */
320         void                    (*suspend)(struct usb_composite_dev *);
321         void                    (*resume)(struct usb_composite_dev *);
322         struct usb_gadget_driver                gadget_driver;
323 };
324
325 extern int usb_composite_probe(struct usb_composite_driver *driver);
326 extern void usb_composite_unregister(struct usb_composite_driver *driver);
327 extern void usb_composite_setup_continue(struct usb_composite_dev *cdev);
328 extern int composite_dev_prepare(struct usb_composite_driver *composite,
329                 struct usb_composite_dev *cdev);
330 void composite_dev_cleanup(struct usb_composite_dev *cdev);
331
332 static inline struct usb_composite_driver *to_cdriver(
333                 struct usb_gadget_driver *gdrv)
334 {
335         return container_of(gdrv, struct usb_composite_driver, gadget_driver);
336 }
337
338 /**
339  * struct usb_composite_device - represents one composite usb gadget
340  * @gadget: read-only, abstracts the gadget's usb peripheral controller
341  * @req: used for control responses; buffer is pre-allocated
342  * @config: the currently active configuration
343  *
344  * One of these devices is allocated and initialized before the
345  * associated device driver's bind() is called.
346  *
347  * OPEN ISSUE:  it appears that some WUSB devices will need to be
348  * built by combining a normal (wired) gadget with a wireless one.
349  * This revision of the gadget framework should probably try to make
350  * sure doing that won't hurt too much.
351  *
352  * One notion for how to handle Wireless USB devices involves:
353  * (a) a second gadget here, discovery mechanism TBD, but likely
354  *     needing separate "register/unregister WUSB gadget" calls;
355  * (b) updates to usb_gadget to include flags "is it wireless",
356  *     "is it wired", plus (presumably in a wrapper structure)
357  *     bandgroup and PHY info;
358  * (c) presumably a wireless_ep wrapping a usb_ep, and reporting
359  *     wireless-specific parameters like maxburst and maxsequence;
360  * (d) configurations that are specific to wireless links;
361  * (e) function drivers that understand wireless configs and will
362  *     support wireless for (additional) function instances;
363  * (f) a function to support association setup (like CBAF), not
364  *     necessarily requiring a wireless adapter;
365  * (g) composite device setup that can create one or more wireless
366  *     configs, including appropriate association setup support;
367  * (h) more, TBD.
368  */
369 struct usb_composite_dev {
370         struct usb_gadget               *gadget;
371         struct usb_request              *req;
372
373         struct usb_configuration        *config;
374
375         /* private: */
376         /* internals */
377         unsigned int                    suspended:1;
378         struct usb_device_descriptor    desc;
379         struct list_head                configs;
380         struct list_head                gstrings;
381         struct usb_composite_driver     *driver;
382         u8                              next_string_id;
383         char                            *def_manufacturer;
384
385         /* the gadget driver won't enable the data pullup
386          * while the deactivation count is nonzero.
387          */
388         unsigned                        deactivations;
389
390         /* the composite driver won't complete the control transfer's
391          * data/status stages till delayed_status is zero.
392          */
393         int                             delayed_status;
394
395         /* protects deactivations and delayed_status counts*/
396         spinlock_t                      lock;
397 };
398
399 extern int usb_string_id(struct usb_composite_dev *c);
400 extern int usb_string_ids_tab(struct usb_composite_dev *c,
401                               struct usb_string *str);
402 extern struct usb_string *usb_gstrings_attach(struct usb_composite_dev *cdev,
403                 struct usb_gadget_strings **sp, unsigned n_strings);
404
405 extern int usb_string_ids_n(struct usb_composite_dev *c, unsigned n);
406
407 extern void composite_disconnect(struct usb_gadget *gadget);
408 extern int composite_setup(struct usb_gadget *gadget,
409                 const struct usb_ctrlrequest *ctrl);
410
411 /*
412  * Some systems will need runtime overrides for the  product identifiers
413  * published in the device descriptor, either numbers or strings or both.
414  * String parameters are in UTF-8 (superset of ASCII's 7 bit characters).
415  */
416 struct usb_composite_overwrite {
417         u16     idVendor;
418         u16     idProduct;
419         u16     bcdDevice;
420         char    *serial_number;
421         char    *manufacturer;
422         char    *product;
423 };
424 #define USB_GADGET_COMPOSITE_OPTIONS()                                  \
425         static struct usb_composite_overwrite coverwrite;               \
426                                                                         \
427         module_param_named(idVendor, coverwrite.idVendor, ushort, S_IRUGO); \
428         MODULE_PARM_DESC(idVendor, "USB Vendor ID");                    \
429                                                                         \
430         module_param_named(idProduct, coverwrite.idProduct, ushort, S_IRUGO); \
431         MODULE_PARM_DESC(idProduct, "USB Product ID");                  \
432                                                                         \
433         module_param_named(bcdDevice, coverwrite.bcdDevice, ushort, S_IRUGO); \
434         MODULE_PARM_DESC(bcdDevice, "USB Device version (BCD)");        \
435                                                                         \
436         module_param_named(iSerialNumber, coverwrite.serial_number, charp, \
437                         S_IRUGO); \
438         MODULE_PARM_DESC(iSerialNumber, "SerialNumber string");         \
439                                                                         \
440         module_param_named(iManufacturer, coverwrite.manufacturer, charp, \
441                         S_IRUGO); \
442         MODULE_PARM_DESC(iManufacturer, "USB Manufacturer string");     \
443                                                                         \
444         module_param_named(iProduct, coverwrite.product, charp, S_IRUGO); \
445         MODULE_PARM_DESC(iProduct, "USB Product string")
446
447 void usb_composite_overwrite_options(struct usb_composite_dev *cdev,
448                 struct usb_composite_overwrite *covr);
449
450 static inline u16 get_default_bcdDevice(void)
451 {
452         u16 bcdDevice;
453
454         bcdDevice = bin2bcd((LINUX_VERSION_CODE >> 16 & 0xff)) << 8;
455         bcdDevice |= bin2bcd((LINUX_VERSION_CODE >> 8 & 0xff));
456         return bcdDevice;
457 }
458
459 struct usb_function_driver {
460         const char *name;
461         struct module *mod;
462         struct list_head list;
463         struct usb_function_instance *(*alloc_inst)(void);
464         struct usb_function *(*alloc_func)(struct usb_function_instance *inst);
465 };
466
467 struct usb_function_instance {
468         struct config_group group;
469         struct list_head cfs_list;
470         struct usb_function_driver *fd;
471         void (*free_func_inst)(struct usb_function_instance *inst);
472 };
473
474 void usb_function_unregister(struct usb_function_driver *f);
475 int usb_function_register(struct usb_function_driver *newf);
476 void usb_put_function_instance(struct usb_function_instance *fi);
477 void usb_put_function(struct usb_function *f);
478 struct usb_function_instance *usb_get_function_instance(const char *name);
479 struct usb_function *usb_get_function(struct usb_function_instance *fi);
480
481 struct usb_configuration *usb_get_config(struct usb_composite_dev *cdev,
482                 int val);
483 int usb_add_config_only(struct usb_composite_dev *cdev,
484                 struct usb_configuration *config);
485 void usb_remove_function(struct usb_configuration *c, struct usb_function *f);
486
487 #define DECLARE_USB_FUNCTION(_name, _inst_alloc, _func_alloc)           \
488         static struct usb_function_driver _name ## usb_func = {         \
489                 .name = __stringify(_name),                             \
490                 .mod  = THIS_MODULE,                                    \
491                 .alloc_inst = _inst_alloc,                              \
492                 .alloc_func = _func_alloc,                              \
493         };                                                              \
494         MODULE_ALIAS("usbfunc:"__stringify(_name));
495
496 #define DECLARE_USB_FUNCTION_INIT(_name, _inst_alloc, _func_alloc)      \
497         DECLARE_USB_FUNCTION(_name, _inst_alloc, _func_alloc)           \
498         static int __init _name ## mod_init(void)                       \
499         {                                                               \
500                 return usb_function_register(&_name ## usb_func);       \
501         }                                                               \
502         static void __exit _name ## mod_exit(void)                      \
503         {                                                               \
504                 usb_function_unregister(&_name ## usb_func);            \
505         }                                                               \
506         module_init(_name ## mod_init);                                 \
507         module_exit(_name ## mod_exit)
508
509 /* messaging utils */
510 #define DBG(d, fmt, args...) \
511         dev_dbg(&(d)->gadget->dev , fmt , ## args)
512 #define VDBG(d, fmt, args...) \
513         dev_vdbg(&(d)->gadget->dev , fmt , ## args)
514 #define ERROR(d, fmt, args...) \
515         dev_err(&(d)->gadget->dev , fmt , ## args)
516 #define WARNING(d, fmt, args...) \
517         dev_warn(&(d)->gadget->dev , fmt , ## args)
518 #define INFO(d, fmt, args...) \
519         dev_info(&(d)->gadget->dev , fmt , ## args)
520
521 #endif  /* __LINUX_USB_COMPOSITE_H */