composite.h 17 KB

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