composite.h 14 KB

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