blob: 53cb0955071904ed4e498d10387b1e6afe64736b [file] [log] [blame]
Lukasz Majewski7010f5b2012-05-02 17:47:02 +02001/*
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 <common.h>
38#include <linux/usb/ch9.h>
39#include <linux/usb/gadget.h>
40#include <usb/lin_gadget_compat.h>
41
42struct usb_configuration;
43
44/**
45 * struct usb_function - describes one function of a configuration
46 * @name: For diagnostics, identifies the function.
47 * @strings: tables of strings, keyed by identifiers assigned during bind()
48 * and by language IDs provided in control requests
49 * @descriptors: Table of full (or low) speed descriptors, using interface and
50 * string identifiers assigned during @bind(). If this pointer is null,
51 * the function will not be available at full speed (or at low speed).
52 * @hs_descriptors: Table of high speed descriptors, using interface and
53 * string identifiers assigned during @bind(). If this pointer is null,
54 * the function will not be available at high speed.
55 * @config: assigned when @usb_add_function() is called; this is the
56 * configuration with which this function is associated.
57 * @bind: Before the gadget can register, all of its functions bind() to the
58 * available resources including string and interface identifiers used
59 * in interface or class descriptors; endpoints; I/O buffers; and so on.
60 * @unbind: Reverses @bind; called as a side effect of unregistering the
61 * driver which added this function.
62 * @set_alt: (REQUIRED) Reconfigures altsettings; function drivers may
63 * initialize usb_ep.driver data at this time (when it is used).
64 * Note that setting an interface to its current altsetting resets
65 * interface state, and that all interfaces have a disabled state.
66 * @get_alt: Returns the active altsetting. If this is not provided,
67 * then only altsetting zero is supported.
68 * @disable: (REQUIRED) Indicates the function should be disabled. Reasons
69 * include host resetting or reconfiguring the gadget, and disconnection.
70 * @setup: Used for interface-specific control requests.
71 * @suspend: Notifies functions when the host stops sending USB traffic.
72 * @resume: Notifies functions when the host restarts USB traffic.
73 *
74 * A single USB function uses one or more interfaces, and should in most
75 * cases support operation at both full and high speeds. Each function is
76 * associated by @usb_add_function() with a one configuration; that function
77 * causes @bind() to be called so resources can be allocated as part of
78 * setting up a gadget driver. Those resources include endpoints, which
79 * should be allocated using @usb_ep_autoconfig().
80 *
81 * To support dual speed operation, a function driver provides descriptors
82 * for both high and full speed operation. Except in rare cases that don't
83 * involve bulk endpoints, each speed needs different endpoint descriptors.
84 *
85 * Function drivers choose their own strategies for managing instance data.
86 * The simplest strategy just declares it "static', which means the function
87 * can only be activated once. If the function needs to be exposed in more
88 * than one configuration at a given speed, it needs to support multiple
89 * usb_function structures (one for each configuration).
90 *
91 * A more complex strategy might encapsulate a @usb_function structure inside
92 * a driver-specific instance structure to allows multiple activations. An
93 * example of multiple activations might be a CDC ACM function that supports
94 * two or more distinct instances within the same configuration, providing
95 * several independent logical data links to a USB host.
96 */
97struct usb_function {
98 const char *name;
99 struct usb_gadget_strings **strings;
100 struct usb_descriptor_header **descriptors;
101 struct usb_descriptor_header **hs_descriptors;
102
103 struct usb_configuration *config;
104
105 /* REVISIT: bind() functions can be marked __init, which
106 * makes trouble for section mismatch analysis. See if
107 * we can't restructure things to avoid mismatching.
108 * Related: unbind() may kfree() but bind() won't...
109 */
110
111 /* configuration management: bind/unbind */
112 int (*bind)(struct usb_configuration *,
113 struct usb_function *);
114 void (*unbind)(struct usb_configuration *,
115 struct usb_function *);
116
117 /* runtime state management */
118 int (*set_alt)(struct usb_function *,
119 unsigned interface, unsigned alt);
120 int (*get_alt)(struct usb_function *,
121 unsigned interface);
122 void (*disable)(struct usb_function *);
123 int (*setup)(struct usb_function *,
124 const struct usb_ctrlrequest *);
125 void (*suspend)(struct usb_function *);
126 void (*resume)(struct usb_function *);
127
128 /* private: */
129 /* internals */
130 struct list_head list;
131 DECLARE_BITMAP(endpoints, 32);
132};
133
134int usb_add_function(struct usb_configuration *, struct usb_function *);
135
136int usb_function_deactivate(struct usb_function *);
137int usb_function_activate(struct usb_function *);
138
139int usb_interface_id(struct usb_configuration *, struct usb_function *);
140
141/**
142 * ep_choose - select descriptor endpoint at current device speed
143 * @g: gadget, connected and running at some speed
144 * @hs: descriptor to use for high speed operation
145 * @fs: descriptor to use for full or low speed operation
146 */
147static inline struct usb_endpoint_descriptor *
148ep_choose(struct usb_gadget *g, struct usb_endpoint_descriptor *hs,
149 struct usb_endpoint_descriptor *fs)
150{
151 if (gadget_is_dualspeed(g) && g->speed == USB_SPEED_HIGH)
152 return hs;
153 return fs;
154}
155
156#define MAX_CONFIG_INTERFACES 16 /* arbitrary; max 255 */
157
158/**
159 * struct usb_configuration - represents one gadget configuration
160 * @label: For diagnostics, describes the configuration.
161 * @strings: Tables of strings, keyed by identifiers assigned during @bind()
162 * and by language IDs provided in control requests.
163 * @descriptors: Table of descriptors preceding all function descriptors.
164 * Examples include OTG and vendor-specific descriptors.
165 * @bind: Called from @usb_add_config() to allocate resources unique to this
166 * configuration and to call @usb_add_function() for each function used.
167 * @unbind: Reverses @bind; called as a side effect of unregistering the
168 * driver which added this configuration.
169 * @setup: Used to delegate control requests that aren't handled by standard
170 * device infrastructure or directed at a specific interface.
171 * @bConfigurationValue: Copied into configuration descriptor.
172 * @iConfiguration: Copied into configuration descriptor.
173 * @bmAttributes: Copied into configuration descriptor.
174 * @bMaxPower: Copied into configuration descriptor.
175 * @cdev: assigned by @usb_add_config() before calling @bind(); this is
176 * the device associated with this configuration.
177 *
178 * Configurations are building blocks for gadget drivers structured around
179 * function drivers. Simple USB gadgets require only one function and one
180 * configuration, and handle dual-speed hardware by always providing the same
181 * functionality. Slightly more complex gadgets may have more than one
182 * single-function configuration at a given speed; or have configurations
183 * that only work at one speed.
184 *
185 * Composite devices are, by definition, ones with configurations which
186 * include more than one function.
187 *
188 * The lifecycle of a usb_configuration includes allocation, initialization
189 * of the fields described above, and calling @usb_add_config() to set up
190 * internal data and bind it to a specific device. The configuration's
191 * @bind() method is then used to initialize all the functions and then
192 * call @usb_add_function() for them.
193 *
194 * Those functions would normally be independant of each other, but that's
195 * not mandatory. CDC WMC devices are an example where functions often
196 * depend on other functions, with some functions subsidiary to others.
197 * Such interdependency may be managed in any way, so long as all of the
198 * descriptors complete by the time the composite driver returns from
199 * its bind() routine.
200 */
201struct usb_configuration {
202 const char *label;
203 struct usb_gadget_strings **strings;
204 const struct usb_descriptor_header **descriptors;
205
206 /* REVISIT: bind() functions can be marked __init, which
207 * makes trouble for section mismatch analysis. See if
208 * we can't restructure things to avoid mismatching...
209 */
210
211 /* configuration management: bind/unbind */
212 int (*bind)(struct usb_configuration *);
213 void (*unbind)(struct usb_configuration *);
214 int (*setup)(struct usb_configuration *,
215 const struct usb_ctrlrequest *);
216
217 /* fields in the config descriptor */
218 u8 bConfigurationValue;
219 u8 iConfiguration;
220 u8 bmAttributes;
221 u8 bMaxPower;
222
223 struct usb_composite_dev *cdev;
224
225 /* private: */
226 /* internals */
227 struct list_head list;
228 struct list_head functions;
229 u8 next_interface_id;
230 unsigned highspeed:1;
231 unsigned fullspeed:1;
232 struct usb_function *interface[MAX_CONFIG_INTERFACES];
233};
234
235int usb_add_config(struct usb_composite_dev *,
236 struct usb_configuration *);
237
238/**
239 * struct usb_composite_driver - groups configurations into a gadget
240 * @name: For diagnostics, identifies the driver.
241 * @dev: Template descriptor for the device, including default device
242 * identifiers.
243 * @strings: tables of strings, keyed by identifiers assigned during bind()
244 * and language IDs provided in control requests
245 * @bind: (REQUIRED) Used to allocate resources that are shared across the
246 * whole device, such as string IDs, and add its configurations using
247 * @usb_add_config(). This may fail by returning a negative errno
248 * value; it should return zero on successful initialization.
249 * @unbind: Reverses @bind(); called as a side effect of unregistering
250 * this driver.
251 * @disconnect: optional driver disconnect method
252 * @suspend: Notifies when the host stops sending USB traffic,
253 * after function notifications
254 * @resume: Notifies configuration when the host restarts USB traffic,
255 * before function notifications
256 *
257 * Devices default to reporting self powered operation. Devices which rely
258 * on bus powered operation should report this in their @bind() method.
259 *
260 * Before returning from @bind, various fields in the template descriptor
261 * may be overridden. These include the idVendor/idProduct/bcdDevice values
262 * normally to bind the appropriate host side driver, and the three strings
263 * (iManufacturer, iProduct, iSerialNumber) normally used to provide user
264 * meaningful device identifiers. (The strings will not be defined unless
265 * they are defined in @dev and @strings.) The correct ep0 maxpacket size
266 * is also reported, as defined by the underlying controller driver.
267 */
268struct usb_composite_driver {
269 const char *name;
270 const struct usb_device_descriptor *dev;
271 struct usb_gadget_strings **strings;
272
273 /* REVISIT: bind() functions can be marked __init, which
274 * makes trouble for section mismatch analysis. See if
275 * we can't restructure things to avoid mismatching...
276 */
277
278 int (*bind)(struct usb_composite_dev *);
279 int (*unbind)(struct usb_composite_dev *);
280
281 void (*disconnect)(struct usb_composite_dev *);
282
283 /* global suspend hooks */
284 void (*suspend)(struct usb_composite_dev *);
285 void (*resume)(struct usb_composite_dev *);
286};
287
288extern int usb_composite_register(struct usb_composite_driver *);
289extern void usb_composite_unregister(struct usb_composite_driver *);
290
291
292/**
293 * struct usb_composite_device - represents one composite usb gadget
294 * @gadget: read-only, abstracts the gadget's usb peripheral controller
295 * @req: used for control responses; buffer is pre-allocated
296 * @bufsiz: size of buffer pre-allocated in @req
297 * @config: the currently active configuration
298 *
299 * One of these devices is allocated and initialized before the
300 * associated device driver's bind() is called.
301 *
302 * OPEN ISSUE: it appears that some WUSB devices will need to be
303 * built by combining a normal (wired) gadget with a wireless one.
304 * This revision of the gadget framework should probably try to make
305 * sure doing that won't hurt too much.
306 *
307 * One notion for how to handle Wireless USB devices involves:
308 * (a) a second gadget here, discovery mechanism TBD, but likely
309 * needing separate "register/unregister WUSB gadget" calls;
310 * (b) updates to usb_gadget to include flags "is it wireless",
311 * "is it wired", plus (presumably in a wrapper structure)
312 * bandgroup and PHY info;
313 * (c) presumably a wireless_ep wrapping a usb_ep, and reporting
314 * wireless-specific parameters like maxburst and maxsequence;
315 * (d) configurations that are specific to wireless links;
316 * (e) function drivers that understand wireless configs and will
317 * support wireless for (additional) function instances;
318 * (f) a function to support association setup (like CBAF), not
319 * necessarily requiring a wireless adapter;
320 * (g) composite device setup that can create one or more wireless
321 * configs, including appropriate association setup support;
322 * (h) more, TBD.
323 */
324struct usb_composite_dev {
325 struct usb_gadget *gadget;
326 struct usb_request *req;
327 unsigned bufsiz;
328
329 struct usb_configuration *config;
330
331 /* private: */
332 /* internals */
333 unsigned int suspended:1;
334 struct usb_device_descriptor desc;
335 struct list_head configs;
336 struct usb_composite_driver *driver;
337 u8 next_string_id;
338
339 /* the gadget driver won't enable the data pullup
340 * while the deactivation count is nonzero.
341 */
342 unsigned deactivations;
343};
344
345extern int usb_string_id(struct usb_composite_dev *c);
346extern int usb_string_ids_tab(struct usb_composite_dev *c,
347 struct usb_string *str);
348extern int usb_string_ids_n(struct usb_composite_dev *c, unsigned n);
349
350#endif /* __LINUX_USB_COMPOSITE_H */