1	/* SPDX-License-Identifier: GPL-2.0 */
2	#ifndef __LINUX_USB_H
3	#define __LINUX_USB_H
4
5	#include <linux/mod_devicetable.h>
6	#include <linux/usb/ch9.h>
7
8	#define USB_MAJOR 180
9	#define USB_DEVICE_MAJOR 189
10
11
12	#ifdef __KERNEL__
13
14	#include <linux/errno.h> /* for -ENODEV */
15	#include <linux/delay.h> /* for mdelay() */
16	#include <linux/interrupt.h> /* for in_interrupt() */
17	#include <linux/list.h> /* for struct list_head */
18	#include <linux/kref.h> /* for struct kref */
19	#include <linux/device.h> /* for struct device */
20	#include <linux/fs.h> /* for struct file_operations */
21	#include <linux/completion.h> /* for struct completion */
22	#include <linux/sched.h> /* for current && schedule_timeout */
23	#include <linux/mutex.h> /* for struct mutex */
24	#include <linux/pm_runtime.h> /* for runtime PM */
25
26	struct usb_device;
27	struct usb_driver;
28
29	/*-------------------------------------------------------------------------*/
30
31	/*
32	* Host-side wrappers for standard USB descriptors ... these are parsed
33	* from the data provided by devices. Parsing turns them from a flat
34	* sequence of descriptors into a hierarchy:
35	*
36	* - devices have one (usually) or more configs;
37	* - configs have one (often) or more interfaces;
38	* - interfaces have one (usually) or more settings;
39	* - each interface setting has zero or (usually) more endpoints.
40	* - a SuperSpeed endpoint has a companion descriptor
41	*
42	* And there might be other descriptors mixed in with those.
43	*
44	* Devices may also have class-specific or vendor-specific descriptors.
45	*/
46
47	struct ep_device;
48
49	/**
50	* struct usb_host_endpoint - host-side endpoint descriptor and queue
51	* @desc: descriptor for this endpoint, wMaxPacketSize in native byteorder
52	* @ss_ep_comp: SuperSpeed companion descriptor for this endpoint
53	* @ssp_isoc_ep_comp: SuperSpeedPlus isoc companion descriptor for this endpoint
54	* @urb_list: urbs queued to this endpoint; maintained by usbcore
55	* @hcpriv: for use by HCD; typically holds hardware dma queue head (QH)
56	* with one or more transfer descriptors (TDs) per urb
57	* @ep_dev: ep_device for sysfs info
58	* @extra: descriptors following this endpoint in the configuration
59	* @extralen: how many bytes of "extra" are valid
60	* @enabled: URBs may be submitted to this endpoint
61	* @streams: number of USB-3 streams allocated on the endpoint
62	*
63	* USB requests are always queued to a given endpoint, identified by a
64	* descriptor within an active interface in a given USB configuration.
65	*/
66	struct usb_host_endpoint {
67	struct usb_endpoint_descriptor desc;
68	struct usb_ss_ep_comp_descriptor ss_ep_comp;
69	struct usb_ssp_isoc_ep_comp_descriptor ssp_isoc_ep_comp;
70	struct list_head urb_list;
71	void *hcpriv;
72	struct ep_device *ep_dev; /* For sysfs info */
73
74	unsigned char *extra; /* Extra descriptors */
75	int extralen;
76	int enabled;
77	int streams;
78	};
79
80	/* host-side wrapper for one interface setting's parsed descriptors */
81	struct usb_host_interface {
82	struct usb_interface_descriptor desc;
83
84	int extralen;
85	unsigned char *extra; /* Extra descriptors */
86
87	/* array of desc.bNumEndpoints endpoints associated with this
88	* interface setting. these will be in no particular order.
89	*/
90	struct usb_host_endpoint *endpoint;
91
92	char *string; /* iInterface string, if present */
93	};
94
95	enum usb_interface_condition {
96	USB_INTERFACE_UNBOUND = 0,
97	USB_INTERFACE_BINDING,
98	USB_INTERFACE_BOUND,
99	USB_INTERFACE_UNBINDING,
100	};
101
102	int __must_check
103	usb_find_common_endpoints(struct usb_host_interface *alt,
104	struct usb_endpoint_descriptor **bulk_in,
105	struct usb_endpoint_descriptor **bulk_out,
106	struct usb_endpoint_descriptor **int_in,
107	struct usb_endpoint_descriptor **int_out);
108
109	int __must_check
110	usb_find_common_endpoints_reverse(struct usb_host_interface *alt,
111	struct usb_endpoint_descriptor **bulk_in,
112	struct usb_endpoint_descriptor **bulk_out,
113	struct usb_endpoint_descriptor **int_in,
114	struct usb_endpoint_descriptor **int_out);
115
116	static inline int __must_check
117	usb_find_bulk_in_endpoint(struct usb_host_interface *alt,
118	struct usb_endpoint_descriptor **bulk_in)
119	{
120	return usb_find_common_endpoints(alt, bulk_in, NULL, NULL, NULL);
121	}
122
123	static inline int __must_check
124	usb_find_bulk_out_endpoint(struct usb_host_interface *alt,
125	struct usb_endpoint_descriptor **bulk_out)
126	{
127	return usb_find_common_endpoints(alt, NULL, bulk_out, NULL, NULL);
128	}
129
130	static inline int __must_check
131	usb_find_int_in_endpoint(struct usb_host_interface *alt,
132	struct usb_endpoint_descriptor **int_in)
133	{
134	return usb_find_common_endpoints(alt, NULL, NULL, int_in, NULL);
135	}
136
137	static inline int __must_check
138	usb_find_int_out_endpoint(struct usb_host_interface *alt,
139	struct usb_endpoint_descriptor **int_out)
140	{
141	return usb_find_common_endpoints(alt, NULL, NULL, NULL, int_out);
142	}
143
144	static inline int __must_check
145	usb_find_last_bulk_in_endpoint(struct usb_host_interface *alt,
146	struct usb_endpoint_descriptor **bulk_in)
147	{
148	return usb_find_common_endpoints_reverse(alt, bulk_in, NULL, NULL, NULL);
149	}
150
151	static inline int __must_check
152	usb_find_last_bulk_out_endpoint(struct usb_host_interface *alt,
153	struct usb_endpoint_descriptor **bulk_out)
154	{
155	return usb_find_common_endpoints_reverse(alt, NULL, bulk_out, NULL, NULL);
156	}
157
158	static inline int __must_check
159	usb_find_last_int_in_endpoint(struct usb_host_interface *alt,
160	struct usb_endpoint_descriptor **int_in)
161	{
162	return usb_find_common_endpoints_reverse(alt, NULL, NULL, int_in, NULL);
163	}
164
165	static inline int __must_check
166	usb_find_last_int_out_endpoint(struct usb_host_interface *alt,
167	struct usb_endpoint_descriptor **int_out)
168	{
169	return usb_find_common_endpoints_reverse(alt, NULL, NULL, NULL, int_out);
170	}
171
172	enum usb_wireless_status {
173	USB_WIRELESS_STATUS_NA = 0,
174	USB_WIRELESS_STATUS_DISCONNECTED,
175	USB_WIRELESS_STATUS_CONNECTED,
176	};
177
178	/**
179	* struct usb_interface - what usb device drivers talk to
180	* @altsetting: array of interface structures, one for each alternate
181	* setting that may be selected. Each one includes a set of
182	* endpoint configurations. They will be in no particular order.
183	* @cur_altsetting: the current altsetting.
184	* @num_altsetting: number of altsettings defined.
185	* @intf_assoc: interface association descriptor
186	* @minor: the minor number assigned to this interface, if this
187	* interface is bound to a driver that uses the USB major number.
188	* If this interface does not use the USB major, this field should
189	* be unused. The driver should set this value in the probe()
190	* function of the driver, after it has been assigned a minor
191	* number from the USB core by calling usb_register_dev().
192	* @condition: binding state of the interface: not bound, binding
193	* (in probe()), bound to a driver, or unbinding (in disconnect())
194	* @sysfs_files_created: sysfs attributes exist
195	* @ep_devs_created: endpoint child pseudo-devices exist
196	* @unregistering: flag set when the interface is being unregistered
197	* @needs_remote_wakeup: flag set when the driver requires remote-wakeup
198	* capability during autosuspend.
199	* @needs_altsetting0: flag set when a set-interface request for altsetting 0
200	* has been deferred.
201	* @needs_binding: flag set when the driver should be re-probed or unbound
202	* following a reset or suspend operation it doesn't support.
203	* @authorized: This allows to (de)authorize individual interfaces instead
204	* a whole device in contrast to the device authorization.
205	* @wireless_status: if the USB device uses a receiver/emitter combo, whether
206	* the emitter is connected.
207	* @wireless_status_work: Used for scheduling wireless status changes
208	* from atomic context.
209	* @dev: driver model's view of this device
210	* @usb_dev: if an interface is bound to the USB major, this will point
211	* to the sysfs representation for that device.
212	* @reset_ws: Used for scheduling resets from atomic context.
213	* @resetting_device: USB core reset the device, so use alt setting 0 as
214	* current; needs bandwidth alloc after reset.
215	*
216	* USB device drivers attach to interfaces on a physical device. Each
217	* interface encapsulates a single high level function, such as feeding
218	* an audio stream to a speaker or reporting a change in a volume control.
219	* Many USB devices only have one interface. The protocol used to talk to
220	* an interface's endpoints can be defined in a usb "class" specification,
221	* or by a product's vendor. The (default) control endpoint is part of
222	* every interface, but is never listed among the interface's descriptors.
223	*
224	* The driver that is bound to the interface can use standard driver model
225	* calls such as dev_get_drvdata() on the dev member of this structure.
226	*
227	* Each interface may have alternate settings. The initial configuration
228	* of a device sets altsetting 0, but the device driver can change
229	* that setting using usb_set_interface(). Alternate settings are often
230	* used to control the use of periodic endpoints, such as by having
231	* different endpoints use different amounts of reserved USB bandwidth.
232	* All standards-conformant USB devices that use isochronous endpoints
233	* will use them in non-default settings.
234	*
235	* The USB specification says that alternate setting numbers must run from
236	* 0 to one less than the total number of alternate settings. But some
237	* devices manage to mess this up, and the structures aren't necessarily
238	* stored in numerical order anyhow. Use usb_altnum_to_altsetting() to
239	* look up an alternate setting in the altsetting array based on its number.
240	*/
241	struct usb_interface {
242	/* array of alternate settings for this interface,
243	* stored in no particular order */
244	struct usb_host_interface *altsetting;
245
246	struct usb_host_interface *cur_altsetting; /* the currently
247	* active alternate setting */
248	unsigned num_altsetting; /* number of alternate settings */
249
250	/* If there is an interface association descriptor then it will list
251	* the associated interfaces */
252	struct usb_interface_assoc_descriptor *intf_assoc;
253
254	int minor; /* minor number this interface is
255	* bound to */
256	enum usb_interface_condition condition; /* state of binding */
257	unsigned sysfs_files_created:1; /* the sysfs attributes exist */
258	unsigned ep_devs_created:1; /* endpoint "devices" exist */
259	unsigned unregistering:1; /* unregistration is in progress */
260	unsigned needs_remote_wakeup:1; /* driver requires remote wakeup */
261	unsigned needs_altsetting0:1; /* switch to altsetting 0 is pending */
262	unsigned needs_binding:1; /* needs delayed unbind/rebind */
263	unsigned resetting_device:1; /* true: bandwidth alloc after reset */
264	unsigned authorized:1; /* used for interface authorization */
265	enum usb_wireless_status wireless_status;
266	struct work_struct wireless_status_work;
267
268	struct device dev; /* interface specific device info */
269	struct device *usb_dev;
270	struct work_struct reset_ws; /* for resets in atomic context */
271	};
272
273	#define to_usb_interface(__dev) container_of_const(__dev, struct usb_interface, dev)
274
275	static inline void *usb_get_intfdata(struct usb_interface *intf)
276	{
277	return dev_get_drvdata(dev: &intf->dev);
278	}
279
280	/**
281	* usb_set_intfdata() - associate driver-specific data with an interface
282	* @intf: USB interface
283	* @data: driver data
284	*
285	* Drivers can use this function in their probe() callbacks to associate
286	* driver-specific data with an interface.
287	*
288	* Note that there is generally no need to clear the driver-data pointer even
289	* if some drivers do so for historical or implementation-specific reasons.
290	*/
291	static inline void usb_set_intfdata(struct usb_interface *intf, void *data)
292	{
293	dev_set_drvdata(dev: &intf->dev, data);
294	}
295
296	struct usb_interface *usb_get_intf(struct usb_interface *intf);
297	void usb_put_intf(struct usb_interface *intf);
298
299	/* Hard limit */
300	#define USB_MAXENDPOINTS 30
301	/* this maximum is arbitrary */
302	#define USB_MAXINTERFACES 32
303	#define USB_MAXIADS (USB_MAXINTERFACES/2)
304
305	bool usb_check_bulk_endpoints(
306	const struct usb_interface *intf, const u8 *ep_addrs);
307	bool usb_check_int_endpoints(
308	const struct usb_interface *intf, const u8 *ep_addrs);
309
310	/*
311	* USB Resume Timer: Every Host controller driver should drive the resume
312	* signalling on the bus for the amount of time defined by this macro.
313	*
314	* That way we will have a 'stable' behavior among all HCDs supported by Linux.
315	*
316	* Note that the USB Specification states we should drive resume for *at least*
317	* 20 ms, but it doesn't give an upper bound. This creates two possible
318	* situations which we want to avoid:
319	*
320	* (a) sometimes an msleep(20) might expire slightly before 20 ms, which causes
321	* us to fail USB Electrical Tests, thus failing Certification
322	*
323	* (b) Some (many) devices actually need more than 20 ms of resume signalling,
324	* and while we can argue that's against the USB Specification, we don't have
325	* control over which devices a certification laboratory will be using for
326	* certification. If CertLab uses a device which was tested against Windows and
327	* that happens to have relaxed resume signalling rules, we might fall into
328	* situations where we fail interoperability and electrical tests.
329	*
330	* In order to avoid both conditions, we're using a 40 ms resume timeout, which
331	* should cope with both LPJ calibration errors and devices not following every
332	* detail of the USB Specification.
333	*/
334	#define USB_RESUME_TIMEOUT 40 /* ms */
335
336	/**
337	* struct usb_interface_cache - long-term representation of a device interface
338	* @num_altsetting: number of altsettings defined.
339	* @ref: reference counter.
340	* @altsetting: variable-length array of interface structures, one for
341	* each alternate setting that may be selected. Each one includes a
342	* set of endpoint configurations. They will be in no particular order.
343	*
344	* These structures persist for the lifetime of a usb_device, unlike
345	* struct usb_interface (which persists only as long as its configuration
346	* is installed). The altsetting arrays can be accessed through these
347	* structures at any time, permitting comparison of configurations and
348	* providing support for the /sys/kernel/debug/usb/devices pseudo-file.
349	*/
350	struct usb_interface_cache {
351	unsigned num_altsetting; /* number of alternate settings */
352	struct kref ref; /* reference counter */
353
354	/* variable-length array of alternate settings for this interface,
355	* stored in no particular order */
356	struct usb_host_interface altsetting[];
357	};
358	#define ref_to_usb_interface_cache(r) \
359	container_of(r, struct usb_interface_cache, ref)
360	#define altsetting_to_usb_interface_cache(a) \
361	container_of(a, struct usb_interface_cache, altsetting[0])
362
363	/**
364	* struct usb_host_config - representation of a device's configuration
365	* @desc: the device's configuration descriptor.
366	* @string: pointer to the cached version of the iConfiguration string, if
367	* present for this configuration.
368	* @intf_assoc: list of any interface association descriptors in this config
369	* @interface: array of pointers to usb_interface structures, one for each
370	* interface in the configuration. The number of interfaces is stored
371	* in desc.bNumInterfaces. These pointers are valid only while the
372	* configuration is active.
373	* @intf_cache: array of pointers to usb_interface_cache structures, one
374	* for each interface in the configuration. These structures exist
375	* for the entire life of the device.
376	* @extra: pointer to buffer containing all extra descriptors associated
377	* with this configuration (those preceding the first interface
378	* descriptor).
379	* @extralen: length of the extra descriptors buffer.
380	*
381	* USB devices may have multiple configurations, but only one can be active
382	* at any time. Each encapsulates a different operational environment;
383	* for example, a dual-speed device would have separate configurations for
384	* full-speed and high-speed operation. The number of configurations
385	* available is stored in the device descriptor as bNumConfigurations.
386	*
387	* A configuration can contain multiple interfaces. Each corresponds to
388	* a different function of the USB device, and all are available whenever
389	* the configuration is active. The USB standard says that interfaces
390	* are supposed to be numbered from 0 to desc.bNumInterfaces-1, but a lot
391	* of devices get this wrong. In addition, the interface array is not
392	* guaranteed to be sorted in numerical order. Use usb_ifnum_to_if() to
393	* look up an interface entry based on its number.
394	*
395	* Device drivers should not attempt to activate configurations. The choice
396	* of which configuration to install is a policy decision based on such
397	* considerations as available power, functionality provided, and the user's
398	* desires (expressed through userspace tools). However, drivers can call
399	* usb_reset_configuration() to reinitialize the current configuration and
400	* all its interfaces.
401	*/
402	struct usb_host_config {
403	struct usb_config_descriptor desc;
404
405	char *string; /* iConfiguration string, if present */
406
407	/* List of any Interface Association Descriptors in this
408	* configuration. */
409	struct usb_interface_assoc_descriptor *intf_assoc[USB_MAXIADS];
410
411	/* the interfaces associated with this configuration,
412	* stored in no particular order */
413	struct usb_interface *interface[USB_MAXINTERFACES];
414
415	/* Interface information available even when this is not the
416	* active configuration */
417	struct usb_interface_cache *intf_cache[USB_MAXINTERFACES];
418
419	unsigned char *extra; /* Extra descriptors */
420	int extralen;
421	};
422
423	/* USB2.0 and USB3.0 device BOS descriptor set */
424	struct usb_host_bos {
425	struct usb_bos_descriptor *desc;
426
427	struct usb_ext_cap_descriptor *ext_cap;
428	struct usb_ss_cap_descriptor *ss_cap;
429	struct usb_ssp_cap_descriptor *ssp_cap;
430	struct usb_ss_container_id_descriptor *ss_id;
431	struct usb_ptm_cap_descriptor *ptm_cap;
432	};
433
434	int __usb_get_extra_descriptor(char *buffer, unsigned size,
435	unsigned char type, void **ptr, size_t min);
436	#define usb_get_extra_descriptor(ifpoint, type, ptr) \
437	__usb_get_extra_descriptor((ifpoint)->extra, \
438	(ifpoint)->extralen, \
439	type, (void **)ptr, sizeof(**(ptr)))
440
441	/* ----------------------------------------------------------------------- */
442
443	/* USB device number allocation bitmap */
444	struct usb_devmap {
445	unsigned long devicemap[128 / (8*sizeof(unsigned long))];
446	};
447
448	/*
449	* Allocated per bus (tree of devices) we have:
450	*/
451	struct usb_bus {
452	struct device *controller; /* host side hardware */
453	struct device *sysdev; /* as seen from firmware or bus */
454	int busnum; /* Bus number (in order of reg) */
455	const char *bus_name; /* stable id (PCI slot_name etc) */
456	u8 uses_pio_for_control; /*
457	* Does the host controller use PIO
458	* for control transfers?
459	*/
460	u8 otg_port; /* 0, or number of OTG/HNP port */
461	unsigned is_b_host:1; /* true during some HNP roleswitches */
462	unsigned b_hnp_enable:1; /* OTG: did A-Host enable HNP? */
463	unsigned no_stop_on_short:1; /*
464	* Quirk: some controllers don't stop
465	* the ep queue on a short transfer
466	* with the URB_SHORT_NOT_OK flag set.
467	*/
468	unsigned no_sg_constraint:1; /* no sg constraint */
469	unsigned sg_tablesize; /* 0 or largest number of sg list entries */
470
471	int devnum_next; /* Next open device number in
472	* round-robin allocation */
473	struct mutex devnum_next_mutex; /* devnum_next mutex */
474
475	struct usb_devmap devmap; /* device address allocation map */
476	struct usb_device *root_hub; /* Root hub */
477	struct usb_bus *hs_companion; /* Companion EHCI bus, if any */
478
479	int bandwidth_allocated; /* on this bus: how much of the time
480	* reserved for periodic (intr/iso)
481	* requests is used, on average?
482	* Units: microseconds/frame.
483	* Limits: Full/low speed reserve 90%,
484	* while high speed reserves 80%.
485	*/
486	int bandwidth_int_reqs; /* number of Interrupt requests */
487	int bandwidth_isoc_reqs; /* number of Isoc. requests */
488
489	unsigned resuming_ports; /* bit array: resuming root-hub ports */
490
491	#if defined(CONFIG_USB_MON) || defined(CONFIG_USB_MON_MODULE)
492	struct mon_bus *mon_bus; /* non-null when associated */
493	int monitored; /* non-zero when monitored */
494	#endif
495	};
496
497	struct usb_dev_state;
498
499	/* ----------------------------------------------------------------------- */
500
501	struct usb_tt;
502
503	enum usb_port_connect_type {
504	USB_PORT_CONNECT_TYPE_UNKNOWN = 0,
505	USB_PORT_CONNECT_TYPE_HOT_PLUG,
506	USB_PORT_CONNECT_TYPE_HARD_WIRED,
507	USB_PORT_NOT_USED,
508	};
509
510	/*
511	* USB port quirks.
512	*/
513
514	/* For the given port, prefer the old (faster) enumeration scheme. */
515	#define USB_PORT_QUIRK_OLD_SCHEME BIT(0)
516
517	/* Decrease TRSTRCY to 10ms during device enumeration. */
518	#define USB_PORT_QUIRK_FAST_ENUM BIT(1)
519
520	/*
521	* USB 2.0 Link Power Management (LPM) parameters.
522	*/
523	struct usb2_lpm_parameters {
524	/* Best effort service latency indicate how long the host will drive
525	* resume on an exit from L1.
526	*/
527	unsigned int besl;
528
529	/* Timeout value in microseconds for the L1 inactivity (LPM) timer.
530	* When the timer counts to zero, the parent hub will initiate a LPM
531	* transition to L1.
532	*/
533	int timeout;
534	};
535
536	/*
537	* USB 3.0 Link Power Management (LPM) parameters.
538	*
539	* PEL and SEL are USB 3.0 Link PM latencies for device-initiated LPM exit.
540	* MEL is the USB 3.0 Link PM latency for host-initiated LPM exit.
541	* All three are stored in nanoseconds.
542	*/
543	struct usb3_lpm_parameters {
544	/*
545	* Maximum exit latency (MEL) for the host to send a packet to the
546	* device (either a Ping for isoc endpoints, or a data packet for
547	* interrupt endpoints), the hubs to decode the packet, and for all hubs
548	* in the path to transition the links to U0.
549	*/
550	unsigned int mel;
551	/*
552	* Maximum exit latency for a device-initiated LPM transition to bring
553	* all links into U0. Abbreviated as "PEL" in section 9.4.12 of the USB
554	* 3.0 spec, with no explanation of what "P" stands for. "Path"?
555	*/
556	unsigned int pel;
557
558	/*
559	* The System Exit Latency (SEL) includes PEL, and three other
560	* latencies. After a device initiates a U0 transition, it will take
561	* some time from when the device sends the ERDY to when it will finally
562	* receive the data packet. Basically, SEL should be the worse-case
563	* latency from when a device starts initiating a U0 transition to when
564	* it will get data.
565	*/
566	unsigned int sel;
567	/*
568	* The idle timeout value that is currently programmed into the parent
569	* hub for this device. When the timer counts to zero, the parent hub
570	* will initiate an LPM transition to either U1 or U2.
571	*/
572	int timeout;
573	};
574
575	/**
576	* struct usb_device - kernel's representation of a USB device
577	* @devnum: device number; address on a USB bus
578	* @devpath: device ID string for use in messages (e.g., /port/...)
579	* @route: tree topology hex string for use with xHCI
580	* @state: device state: configured, not attached, etc.
581	* @speed: device speed: high/full/low (or error)
582	* @rx_lanes: number of rx lanes in use, USB 3.2 adds dual-lane support
583	* @tx_lanes: number of tx lanes in use, USB 3.2 adds dual-lane support
584	* @ssp_rate: SuperSpeed Plus phy signaling rate and lane count
585	* @tt: Transaction Translator info; used with low/full speed dev, highspeed hub
586	* @ttport: device port on that tt hub
587	* @toggle: one bit for each endpoint, with ([0] = IN, [1] = OUT) endpoints
588	* @parent: our hub, unless we're the root
589	* @bus: bus we're part of
590	* @ep0: endpoint 0 data (default control pipe)
591	* @dev: generic device interface
592	* @descriptor: USB device descriptor
593	* @bos: USB device BOS descriptor set
594	* @config: all of the device's configs
595	* @actconfig: the active configuration
596	* @ep_in: array of IN endpoints
597	* @ep_out: array of OUT endpoints
598	* @rawdescriptors: raw descriptors for each config
599	* @bus_mA: Current available from the bus
600	* @portnum: parent port number (origin 1)
601	* @level: number of USB hub ancestors
602	* @devaddr: device address, XHCI: assigned by HW, others: same as devnum
603	* @can_submit: URBs may be submitted
604	* @persist_enabled: USB_PERSIST enabled for this device
605	* @reset_in_progress: the device is being reset
606	* @have_langid: whether string_langid is valid
607	* @authorized: policy has said we can use it;
608	* (user space) policy determines if we authorize this device to be
609	* used or not. By default, wired USB devices are authorized.
610	* WUSB devices are not, until we authorize them from user space.
611	* FIXME -- complete doc
612	* @authenticated: Crypto authentication passed
613	* @lpm_capable: device supports LPM
614	* @lpm_devinit_allow: Allow USB3 device initiated LPM, exit latency is in range
615	* @usb2_hw_lpm_capable: device can perform USB2 hardware LPM
616	* @usb2_hw_lpm_besl_capable: device can perform USB2 hardware BESL LPM
617	* @usb2_hw_lpm_enabled: USB2 hardware LPM is enabled
618	* @usb2_hw_lpm_allowed: Userspace allows USB 2.0 LPM to be enabled
619	* @usb3_lpm_u1_enabled: USB3 hardware U1 LPM enabled
620	* @usb3_lpm_u2_enabled: USB3 hardware U2 LPM enabled
621	* @string_langid: language ID for strings
622	* @product: iProduct string, if present (static)
623	* @manufacturer: iManufacturer string, if present (static)
624	* @serial: iSerialNumber string, if present (static)
625	* @filelist: usbfs files that are open to this device
626	* @maxchild: number of ports if hub
627	* @quirks: quirks of the whole device
628	* @urbnum: number of URBs submitted for the whole device
629	* @active_duration: total time device is not suspended
630	* @connect_time: time device was first connected
631	* @do_remote_wakeup: remote wakeup should be enabled
632	* @reset_resume: needs reset instead of resume
633	* @port_is_suspended: the upstream port is suspended (L2 or U3)
634	* @slot_id: Slot ID assigned by xHCI
635	* @removable: Device can be physically removed from this port
636	* @l1_params: best effor service latency for USB2 L1 LPM state, and L1 timeout.
637	* @u1_params: exit latencies for USB3 U1 LPM state, and hub-initiated timeout.
638	* @u2_params: exit latencies for USB3 U2 LPM state, and hub-initiated timeout.
639	* @lpm_disable_count: Ref count used by usb_disable_lpm() and usb_enable_lpm()
640	* to keep track of the number of functions that require USB 3.0 Link Power
641	* Management to be disabled for this usb_device. This count should only
642	* be manipulated by those functions, with the bandwidth_mutex is held.
643	* @hub_delay: cached value consisting of:
644	* parent->hub_delay + wHubDelay + tTPTransmissionDelay (40ns)
645	* Will be used as wValue for SetIsochDelay requests.
646	* @use_generic_driver: ask driver core to reprobe using the generic driver.
647	*
648	* Notes:
649	* Usbcore drivers should not set usbdev->state directly. Instead use
650	* usb_set_device_state().
651	*/
652	struct usb_device {
653	int devnum;
654	char devpath[16];
655	u32 route;
656	enum usb_device_state state;
657	enum usb_device_speed speed;
658	unsigned int rx_lanes;
659	unsigned int tx_lanes;
660	enum usb_ssp_rate ssp_rate;
661
662	struct usb_tt *tt;
663	int ttport;
664
665	unsigned int toggle[2];
666
667	struct usb_device *parent;
668	struct usb_bus *bus;
669	struct usb_host_endpoint ep0;
670
671	struct device dev;
672
673	struct usb_device_descriptor descriptor;
674	struct usb_host_bos *bos;
675	struct usb_host_config *config;
676
677	struct usb_host_config *actconfig;
678	struct usb_host_endpoint *ep_in[16];
679	struct usb_host_endpoint *ep_out[16];
680
681	char **rawdescriptors;
682
683	unsigned short bus_mA;
684	u8 portnum;
685	u8 level;
686	u8 devaddr;
687
688	unsigned can_submit:1;
689	unsigned persist_enabled:1;
690	unsigned reset_in_progress:1;
691	unsigned have_langid:1;
692	unsigned authorized:1;
693	unsigned authenticated:1;
694	unsigned lpm_capable:1;
695	unsigned lpm_devinit_allow:1;
696	unsigned usb2_hw_lpm_capable:1;
697	unsigned usb2_hw_lpm_besl_capable:1;
698	unsigned usb2_hw_lpm_enabled:1;
699	unsigned usb2_hw_lpm_allowed:1;
700	unsigned usb3_lpm_u1_enabled:1;
701	unsigned usb3_lpm_u2_enabled:1;
702	int string_langid;
703
704	/* static strings from the device */
705	char *product;
706	char *manufacturer;
707	char *serial;
708
709	struct list_head filelist;
710
711	int maxchild;
712
713	u32 quirks;
714	atomic_t urbnum;
715
716	unsigned long active_duration;
717
718	unsigned long connect_time;
719
720	unsigned do_remote_wakeup:1;
721	unsigned reset_resume:1;
722	unsigned port_is_suspended:1;
723
724	int slot_id;
725	struct usb2_lpm_parameters l1_params;
726	struct usb3_lpm_parameters u1_params;
727	struct usb3_lpm_parameters u2_params;
728	unsigned lpm_disable_count;
729
730	u16 hub_delay;
731	unsigned use_generic_driver:1;
732	};
733
734	#define to_usb_device(__dev) container_of_const(__dev, struct usb_device, dev)
735
736	static inline struct usb_device *__intf_to_usbdev(struct usb_interface *intf)
737	{
738	return to_usb_device(intf->dev.parent);
739	}
740	static inline const struct usb_device *__intf_to_usbdev_const(const struct usb_interface *intf)
741	{
742	return to_usb_device((const struct device *)intf->dev.parent);
743	}
744
745	#define interface_to_usbdev(intf) \
746	_Generic((intf), \
747	const struct usb_interface *: __intf_to_usbdev_const, \
748	struct usb_interface *: __intf_to_usbdev)(intf)
749
750	extern struct usb_device *usb_get_dev(struct usb_device *dev);
751	extern void usb_put_dev(struct usb_device *dev);
752	extern struct usb_device *usb_hub_find_child(struct usb_device *hdev,
753	int port1);
754
755	/**
756	* usb_hub_for_each_child - iterate over all child devices on the hub
757	* @hdev: USB device belonging to the usb hub
758	* @port1: portnum associated with child device
759	* @child: child device pointer
760	*/
761	#define usb_hub_for_each_child(hdev, port1, child) \
762	for (port1 = 1, child = usb_hub_find_child(hdev, port1); \
763	port1 <= hdev->maxchild; \
764	child = usb_hub_find_child(hdev, ++port1)) \
765	if (!child) continue; else
766
767	/* USB device locking */
768	#define usb_lock_device(udev) device_lock(&(udev)->dev)
769	#define usb_unlock_device(udev) device_unlock(&(udev)->dev)
770	#define usb_lock_device_interruptible(udev) device_lock_interruptible(&(udev)->dev)
771	#define usb_trylock_device(udev) device_trylock(&(udev)->dev)
772	extern int usb_lock_device_for_reset(struct usb_device *udev,
773	const struct usb_interface *iface);
774
775	/* USB port reset for device reinitialization */
776	extern int usb_reset_device(struct usb_device *dev);
777	extern void usb_queue_reset_device(struct usb_interface *dev);
778
779	extern struct device *usb_intf_get_dma_device(struct usb_interface *intf);
780
781	#ifdef CONFIG_ACPI
782	extern int usb_acpi_set_power_state(struct usb_device *hdev, int index,
783	bool enable);
784	extern bool usb_acpi_power_manageable(struct usb_device *hdev, int index);
785	extern int usb_acpi_port_lpm_incapable(struct usb_device *hdev, int index);
786	#else
787	static inline int usb_acpi_set_power_state(struct usb_device *hdev, int index,
788	bool enable) { return 0; }
789	static inline bool usb_acpi_power_manageable(struct usb_device *hdev, int index)
790	{ return true; }
791	static inline int usb_acpi_port_lpm_incapable(struct usb_device *hdev, int index)
792	{ return 0; }
793	#endif
794
795	/* USB autosuspend and autoresume */
796	#ifdef CONFIG_PM
797	extern void usb_enable_autosuspend(struct usb_device *udev);
798	extern void usb_disable_autosuspend(struct usb_device *udev);
799
800	extern int usb_autopm_get_interface(struct usb_interface *intf);
801	extern void usb_autopm_put_interface(struct usb_interface *intf);
802	extern int usb_autopm_get_interface_async(struct usb_interface *intf);
803	extern void usb_autopm_put_interface_async(struct usb_interface *intf);
804	extern void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
805	extern void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
806
807	static inline void usb_mark_last_busy(struct usb_device *udev)
808	{
809	pm_runtime_mark_last_busy(dev: &udev->dev);
810	}
811
812	#else
813
814	static inline int usb_enable_autosuspend(struct usb_device *udev)
815	{ return 0; }
816	static inline int usb_disable_autosuspend(struct usb_device *udev)
817	{ return 0; }
818
819	static inline int usb_autopm_get_interface(struct usb_interface *intf)
820	{ return 0; }
821	static inline int usb_autopm_get_interface_async(struct usb_interface *intf)
822	{ return 0; }
823
824	static inline void usb_autopm_put_interface(struct usb_interface *intf)
825	{ }
826	static inline void usb_autopm_put_interface_async(struct usb_interface *intf)
827	{ }
828	static inline void usb_autopm_get_interface_no_resume(
829	struct usb_interface *intf)
830	{ }
831	static inline void usb_autopm_put_interface_no_suspend(
832	struct usb_interface *intf)
833	{ }
834	static inline void usb_mark_last_busy(struct usb_device *udev)
835	{ }
836	#endif
837
838	extern int usb_disable_lpm(struct usb_device *udev);
839	extern void usb_enable_lpm(struct usb_device *udev);
840	/* Same as above, but these functions lock/unlock the bandwidth_mutex. */
841	extern int usb_unlocked_disable_lpm(struct usb_device *udev);
842	extern void usb_unlocked_enable_lpm(struct usb_device *udev);
843
844	extern int usb_disable_ltm(struct usb_device *udev);
845	extern void usb_enable_ltm(struct usb_device *udev);
846
847	static inline bool usb_device_supports_ltm(struct usb_device *udev)
848	{
849	if (udev->speed < USB_SPEED_SUPER || !udev->bos || !udev->bos->ss_cap)
850	return false;
851	return udev->bos->ss_cap->bmAttributes & USB_LTM_SUPPORT;
852	}
853
854	static inline bool usb_device_no_sg_constraint(struct usb_device *udev)
855	{
856	return udev && udev->bus && udev->bus->no_sg_constraint;
857	}
858
859
860	/*-------------------------------------------------------------------------*/
861
862	/* for drivers using iso endpoints */
863	extern int usb_get_current_frame_number(struct usb_device *usb_dev);
864
865	/* Sets up a group of bulk endpoints to support multiple stream IDs. */
866	extern int usb_alloc_streams(struct usb_interface *interface,
867	struct usb_host_endpoint **eps, unsigned int num_eps,
868	unsigned int num_streams, gfp_t mem_flags);
869
870	/* Reverts a group of bulk endpoints back to not using stream IDs. */
871	extern int usb_free_streams(struct usb_interface *interface,
872	struct usb_host_endpoint **eps, unsigned int num_eps,
873	gfp_t mem_flags);
874
875	/* used these for multi-interface device registration */
876	extern int usb_driver_claim_interface(struct usb_driver *driver,
877	struct usb_interface *iface, void *data);
878
879	/**
880	* usb_interface_claimed - returns true iff an interface is claimed
881	* @iface: the interface being checked
882	*
883	* Return: %true (nonzero) iff the interface is claimed, else %false
884	* (zero).
885	*
886	* Note:
887	* Callers must own the driver model's usb bus readlock. So driver
888	* probe() entries don't need extra locking, but other call contexts
889	* may need to explicitly claim that lock.
890	*
891	*/
892	static inline int usb_interface_claimed(struct usb_interface *iface)
893	{
894	return (iface->dev.driver != NULL);
895	}
896
897	extern void usb_driver_release_interface(struct usb_driver *driver,
898	struct usb_interface *iface);
899
900	int usb_set_wireless_status(struct usb_interface *iface,
901	enum usb_wireless_status status);
902
903	const struct usb_device_id *usb_match_id(struct usb_interface *interface,
904	const struct usb_device_id *id);
905	extern int usb_match_one_id(struct usb_interface *interface,
906	const struct usb_device_id *id);
907
908	extern int usb_for_each_dev(void *data, int (*fn)(struct usb_device *, void *));
909	extern struct usb_interface *usb_find_interface(struct usb_driver *drv,
910	int minor);
911	extern struct usb_interface *usb_ifnum_to_if(const struct usb_device *dev,
912	unsigned ifnum);
913	extern struct usb_host_interface *usb_altnum_to_altsetting(
914	const struct usb_interface *intf, unsigned int altnum);
915	extern struct usb_host_interface *usb_find_alt_setting(
916	struct usb_host_config *config,
917	unsigned int iface_num,
918	unsigned int alt_num);
919
920	/* port claiming functions */
921	int usb_hub_claim_port(struct usb_device *hdev, unsigned port1,
922	struct usb_dev_state *owner);
923	int usb_hub_release_port(struct usb_device *hdev, unsigned port1,
924	struct usb_dev_state *owner);
925
926	/**
927	* usb_make_path - returns stable device path in the usb tree
928	* @dev: the device whose path is being constructed
929	* @buf: where to put the string
930	* @size: how big is "buf"?
931	*
932	* Return: Length of the string (> 0) or negative if size was too small.
933	*
934	* Note:
935	* This identifier is intended to be "stable", reflecting physical paths in
936	* hardware such as physical bus addresses for host controllers or ports on
937	* USB hubs. That makes it stay the same until systems are physically
938	* reconfigured, by re-cabling a tree of USB devices or by moving USB host
939	* controllers. Adding and removing devices, including virtual root hubs
940	* in host controller driver modules, does not change these path identifiers;
941	* neither does rebooting or re-enumerating. These are more useful identifiers
942	* than changeable ("unstable") ones like bus numbers or device addresses.
943	*
944	* With a partial exception for devices connected to USB 2.0 root hubs, these
945	* identifiers are also predictable. So long as the device tree isn't changed,
946	* plugging any USB device into a given hub port always gives it the same path.
947	* Because of the use of "companion" controllers, devices connected to ports on
948	* USB 2.0 root hubs (EHCI host controllers) will get one path ID if they are
949	* high speed, and a different one if they are full or low speed.
950	*/
951	static inline int usb_make_path(struct usb_device *dev, char *buf, size_t size)
952	{
953	int actual;
954	actual = snprintf(buf, size, fmt: "usb-%s-%s", dev->bus->bus_name,
955	dev->devpath);
956	return (actual >= (int)size) ? -1 : actual;
957	}
958
959	/*-------------------------------------------------------------------------*/
960
961	#define USB_DEVICE_ID_MATCH_DEVICE \
962	(USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
963	#define USB_DEVICE_ID_MATCH_DEV_RANGE \
964	(USB_DEVICE_ID_MATCH_DEV_LO | USB_DEVICE_ID_MATCH_DEV_HI)
965	#define USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION \
966	(USB_DEVICE_ID_MATCH_DEVICE | USB_DEVICE_ID_MATCH_DEV_RANGE)
967	#define USB_DEVICE_ID_MATCH_DEV_INFO \
968	(USB_DEVICE_ID_MATCH_DEV_CLASS | \
969	USB_DEVICE_ID_MATCH_DEV_SUBCLASS | \
970	USB_DEVICE_ID_MATCH_DEV_PROTOCOL)
971	#define USB_DEVICE_ID_MATCH_INT_INFO \
972	(USB_DEVICE_ID_MATCH_INT_CLASS | \
973	USB_DEVICE_ID_MATCH_INT_SUBCLASS | \
974	USB_DEVICE_ID_MATCH_INT_PROTOCOL)
975
976	/**
977	* USB_DEVICE - macro used to describe a specific usb device
978	* @vend: the 16 bit USB Vendor ID
979	* @prod: the 16 bit USB Product ID
980	*
981	* This macro is used to create a struct usb_device_id that matches a
982	* specific device.
983	*/
984	#define USB_DEVICE(vend, prod) \
985	.match_flags = USB_DEVICE_ID_MATCH_DEVICE, \
986	.idVendor = (vend), \
987	.idProduct = (prod)
988	/**
989	* USB_DEVICE_VER - describe a specific usb device with a version range
990	* @vend: the 16 bit USB Vendor ID
991	* @prod: the 16 bit USB Product ID
992	* @lo: the bcdDevice_lo value
993	* @hi: the bcdDevice_hi value
994	*
995	* This macro is used to create a struct usb_device_id that matches a
996	* specific device, with a version range.
997	*/
998	#define USB_DEVICE_VER(vend, prod, lo, hi) \
999	.match_flags = USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION, \
1000	.idVendor = (vend), \
1001	.idProduct = (prod), \
1002	.bcdDevice_lo = (lo), \
1003	.bcdDevice_hi = (hi)
1004
1005	/**
1006	* USB_DEVICE_INTERFACE_CLASS - describe a usb device with a specific interface class
1007	* @vend: the 16 bit USB Vendor ID
1008	* @prod: the 16 bit USB Product ID
1009	* @cl: bInterfaceClass value
1010	*
1011	* This macro is used to create a struct usb_device_id that matches a
1012	* specific interface class of devices.
1013	*/
1014	#define USB_DEVICE_INTERFACE_CLASS(vend, prod, cl) \
1015	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
1016	USB_DEVICE_ID_MATCH_INT_CLASS, \
1017	.idVendor = (vend), \
1018	.idProduct = (prod), \
1019	.bInterfaceClass = (cl)
1020
1021	/**
1022	* USB_DEVICE_INTERFACE_PROTOCOL - describe a usb device with a specific interface protocol
1023	* @vend: the 16 bit USB Vendor ID
1024	* @prod: the 16 bit USB Product ID
1025	* @pr: bInterfaceProtocol value
1026	*
1027	* This macro is used to create a struct usb_device_id that matches a
1028	* specific interface protocol of devices.
1029	*/
1030	#define USB_DEVICE_INTERFACE_PROTOCOL(vend, prod, pr) \
1031	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
1032	USB_DEVICE_ID_MATCH_INT_PROTOCOL, \
1033	.idVendor = (vend), \
1034	.idProduct = (prod), \
1035	.bInterfaceProtocol = (pr)
1036
1037	/**
1038	* USB_DEVICE_INTERFACE_NUMBER - describe a usb device with a specific interface number
1039	* @vend: the 16 bit USB Vendor ID
1040	* @prod: the 16 bit USB Product ID
1041	* @num: bInterfaceNumber value
1042	*
1043	* This macro is used to create a struct usb_device_id that matches a
1044	* specific interface number of devices.
1045	*/
1046	#define USB_DEVICE_INTERFACE_NUMBER(vend, prod, num) \
1047	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
1048	USB_DEVICE_ID_MATCH_INT_NUMBER, \
1049	.idVendor = (vend), \
1050	.idProduct = (prod), \
1051	.bInterfaceNumber = (num)
1052
1053	/**
1054	* USB_DEVICE_INFO - macro used to describe a class of usb devices
1055	* @cl: bDeviceClass value
1056	* @sc: bDeviceSubClass value
1057	* @pr: bDeviceProtocol value
1058	*
1059	* This macro is used to create a struct usb_device_id that matches a
1060	* specific class of devices.
1061	*/
1062	#define USB_DEVICE_INFO(cl, sc, pr) \
1063	.match_flags = USB_DEVICE_ID_MATCH_DEV_INFO, \
1064	.bDeviceClass = (cl), \
1065	.bDeviceSubClass = (sc), \
1066	.bDeviceProtocol = (pr)
1067
1068	/**
1069	* USB_INTERFACE_INFO - macro used to describe a class of usb interfaces
1070	* @cl: bInterfaceClass value
1071	* @sc: bInterfaceSubClass value
1072	* @pr: bInterfaceProtocol value
1073	*
1074	* This macro is used to create a struct usb_device_id that matches a
1075	* specific class of interfaces.
1076	*/
1077	#define USB_INTERFACE_INFO(cl, sc, pr) \
1078	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO, \
1079	.bInterfaceClass = (cl), \
1080	.bInterfaceSubClass = (sc), \
1081	.bInterfaceProtocol = (pr)
1082
1083	/**
1084	* USB_DEVICE_AND_INTERFACE_INFO - describe a specific usb device with a class of usb interfaces
1085	* @vend: the 16 bit USB Vendor ID
1086	* @prod: the 16 bit USB Product ID
1087	* @cl: bInterfaceClass value
1088	* @sc: bInterfaceSubClass value
1089	* @pr: bInterfaceProtocol value
1090	*
1091	* This macro is used to create a struct usb_device_id that matches a
1092	* specific device with a specific class of interfaces.
1093	*
1094	* This is especially useful when explicitly matching devices that have
1095	* vendor specific bDeviceClass values, but standards-compliant interfaces.
1096	*/
1097	#define USB_DEVICE_AND_INTERFACE_INFO(vend, prod, cl, sc, pr) \
1098	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
1099	| USB_DEVICE_ID_MATCH_DEVICE, \
1100	.idVendor = (vend), \
1101	.idProduct = (prod), \
1102	.bInterfaceClass = (cl), \
1103	.bInterfaceSubClass = (sc), \
1104	.bInterfaceProtocol = (pr)
1105
1106	/**
1107	* USB_VENDOR_AND_INTERFACE_INFO - describe a specific usb vendor with a class of usb interfaces
1108	* @vend: the 16 bit USB Vendor ID
1109	* @cl: bInterfaceClass value
1110	* @sc: bInterfaceSubClass value
1111	* @pr: bInterfaceProtocol value
1112	*
1113	* This macro is used to create a struct usb_device_id that matches a
1114	* specific vendor with a specific class of interfaces.
1115	*
1116	* This is especially useful when explicitly matching devices that have
1117	* vendor specific bDeviceClass values, but standards-compliant interfaces.
1118	*/
1119	#define USB_VENDOR_AND_INTERFACE_INFO(vend, cl, sc, pr) \
1120	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
1121	| USB_DEVICE_ID_MATCH_VENDOR, \
1122	.idVendor = (vend), \
1123	.bInterfaceClass = (cl), \
1124	.bInterfaceSubClass = (sc), \
1125	.bInterfaceProtocol = (pr)
1126
1127	/* ----------------------------------------------------------------------- */
1128
1129	/* Stuff for dynamic usb ids */
1130	struct usb_dynids {
1131	spinlock_t lock;
1132	struct list_head list;
1133	};
1134
1135	struct usb_dynid {
1136	struct list_head node;
1137	struct usb_device_id id;
1138	};
1139
1140	extern ssize_t usb_store_new_id(struct usb_dynids *dynids,
1141	const struct usb_device_id *id_table,
1142	struct device_driver *driver,
1143	const char *buf, size_t count);
1144
1145	extern ssize_t usb_show_dynids(struct usb_dynids *dynids, char *buf);
1146
1147	/**
1148	* struct usbdrv_wrap - wrapper for driver-model structure
1149	* @driver: The driver-model core driver structure.
1150	* @for_devices: Non-zero for device drivers, 0 for interface drivers.
1151	*/
1152	struct usbdrv_wrap {
1153	struct device_driver driver;
1154	int for_devices;
1155	};
1156
1157	/**
1158	* struct usb_driver - identifies USB interface driver to usbcore
1159	* @name: The driver name should be unique among USB drivers,
1160	* and should normally be the same as the module name.
1161	* @probe: Called to see if the driver is willing to manage a particular
1162	* interface on a device. If it is, probe returns zero and uses
1163	* usb_set_intfdata() to associate driver-specific data with the
1164	* interface. It may also use usb_set_interface() to specify the
1165	* appropriate altsetting. If unwilling to manage the interface,
1166	* return -ENODEV, if genuine IO errors occurred, an appropriate
1167	* negative errno value.
1168	* @disconnect: Called when the interface is no longer accessible, usually
1169	* because its device has been (or is being) disconnected or the
1170	* driver module is being unloaded.
1171	* @unlocked_ioctl: Used for drivers that want to talk to userspace through
1172	* the "usbfs" filesystem. This lets devices provide ways to
1173	* expose information to user space regardless of where they
1174	* do (or don't) show up otherwise in the filesystem.
1175	* @suspend: Called when the device is going to be suspended by the
1176	* system either from system sleep or runtime suspend context. The
1177	* return value will be ignored in system sleep context, so do NOT
1178	* try to continue using the device if suspend fails in this case.
1179	* Instead, let the resume or reset-resume routine recover from
1180	* the failure.
1181	* @resume: Called when the device is being resumed by the system.
1182	* @reset_resume: Called when the suspended device has been reset instead
1183	* of being resumed.
1184	* @pre_reset: Called by usb_reset_device() when the device is about to be
1185	* reset. This routine must not return until the driver has no active
1186	* URBs for the device, and no more URBs may be submitted until the
1187	* post_reset method is called.
1188	* @post_reset: Called by usb_reset_device() after the device
1189	* has been reset
1190	* @id_table: USB drivers use ID table to support hotplugging.
1191	* Export this with MODULE_DEVICE_TABLE(usb,...). This must be set
1192	* or your driver's probe function will never get called.
1193	* @dev_groups: Attributes attached to the device that will be created once it
1194	* is bound to the driver.
1195	* @dynids: used internally to hold the list of dynamically added device
1196	* ids for this driver.
1197	* @drvwrap: Driver-model core structure wrapper.
1198	* @no_dynamic_id: if set to 1, the USB core will not allow dynamic ids to be
1199	* added to this driver by preventing the sysfs file from being created.
1200	* @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
1201	* for interfaces bound to this driver.
1202	* @soft_unbind: if set to 1, the USB core will not kill URBs and disable
1203	* endpoints before calling the driver's disconnect method.
1204	* @disable_hub_initiated_lpm: if set to 1, the USB core will not allow hubs
1205	* to initiate lower power link state transitions when an idle timeout
1206	* occurs. Device-initiated USB 3.0 link PM will still be allowed.
1207	*
1208	* USB interface drivers must provide a name, probe() and disconnect()
1209	* methods, and an id_table. Other driver fields are optional.
1210	*
1211	* The id_table is used in hotplugging. It holds a set of descriptors,
1212	* and specialized data may be associated with each entry. That table
1213	* is used by both user and kernel mode hotplugging support.
1214	*
1215	* The probe() and disconnect() methods are called in a context where
1216	* they can sleep, but they should avoid abusing the privilege. Most
1217	* work to connect to a device should be done when the device is opened,
1218	* and undone at the last close. The disconnect code needs to address
1219	* concurrency issues with respect to open() and close() methods, as
1220	* well as forcing all pending I/O requests to complete (by unlinking
1221	* them as necessary, and blocking until the unlinks complete).
1222	*/
1223	struct usb_driver {
1224	const char *name;
1225
1226	int (*probe) (struct usb_interface *intf,
1227	const struct usb_device_id *id);
1228
1229	void (*disconnect) (struct usb_interface *intf);
1230
1231	int (*unlocked_ioctl) (struct usb_interface *intf, unsigned int code,
1232	void *buf);
1233
1234	int (*suspend) (struct usb_interface *intf, pm_message_t message);
1235	int (*resume) (struct usb_interface *intf);
1236	int (*reset_resume)(struct usb_interface *intf);
1237
1238	int (*pre_reset)(struct usb_interface *intf);
1239	int (*post_reset)(struct usb_interface *intf);
1240
1241	const struct usb_device_id *id_table;
1242	const struct attribute_group **dev_groups;
1243
1244	struct usb_dynids dynids;
1245	struct usbdrv_wrap drvwrap;
1246	unsigned int no_dynamic_id:1;
1247	unsigned int supports_autosuspend:1;
1248	unsigned int disable_hub_initiated_lpm:1;
1249	unsigned int soft_unbind:1;
1250	};
1251	#define to_usb_driver(d) container_of(d, struct usb_driver, drvwrap.driver)
1252
1253	/**
1254	* struct usb_device_driver - identifies USB device driver to usbcore
1255	* @name: The driver name should be unique among USB drivers,
1256	* and should normally be the same as the module name.
1257	* @match: If set, used for better device/driver matching.
1258	* @probe: Called to see if the driver is willing to manage a particular
1259	* device. If it is, probe returns zero and uses dev_set_drvdata()
1260	* to associate driver-specific data with the device. If unwilling
1261	* to manage the device, return a negative errno value.
1262	* @disconnect: Called when the device is no longer accessible, usually
1263	* because it has been (or is being) disconnected or the driver's
1264	* module is being unloaded.
1265	* @suspend: Called when the device is going to be suspended by the system.
1266	* @resume: Called when the device is being resumed by the system.
1267	* @dev_groups: Attributes attached to the device that will be created once it
1268	* is bound to the driver.
1269	* @drvwrap: Driver-model core structure wrapper.
1270	* @id_table: used with @match() to select better matching driver at
1271	* probe() time.
1272	* @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
1273	* for devices bound to this driver.
1274	* @generic_subclass: if set to 1, the generic USB driver's probe, disconnect,
1275	* resume and suspend functions will be called in addition to the driver's
1276	* own, so this part of the setup does not need to be replicated.
1277	*
1278	* USB drivers must provide all the fields listed above except drvwrap,
1279	* match, and id_table.
1280	*/
1281	struct usb_device_driver {
1282	const char *name;
1283
1284	bool (*match) (struct usb_device *udev);
1285	int (*probe) (struct usb_device *udev);
1286	void (*disconnect) (struct usb_device *udev);
1287
1288	int (*suspend) (struct usb_device *udev, pm_message_t message);
1289	int (*resume) (struct usb_device *udev, pm_message_t message);
1290	const struct attribute_group **dev_groups;
1291	struct usbdrv_wrap drvwrap;
1292	const struct usb_device_id *id_table;
1293	unsigned int supports_autosuspend:1;
1294	unsigned int generic_subclass:1;
1295	};
1296	#define to_usb_device_driver(d) container_of(d, struct usb_device_driver, \
1297	drvwrap.driver)
1298
1299	/**
1300	* struct usb_class_driver - identifies a USB driver that wants to use the USB major number
1301	* @name: the usb class device name for this driver. Will show up in sysfs.
1302	* @devnode: Callback to provide a naming hint for a possible
1303	* device node to create.
1304	* @fops: pointer to the struct file_operations of this driver.
1305	* @minor_base: the start of the minor range for this driver.
1306	*
1307	* This structure is used for the usb_register_dev() and
1308	* usb_deregister_dev() functions, to consolidate a number of the
1309	* parameters used for them.
1310	*/
1311	struct usb_class_driver {
1312	char *name;
1313	char *(*devnode)(const struct device *dev, umode_t *mode);
1314	const struct file_operations *fops;
1315	int minor_base;
1316	};
1317
1318	/*
1319	* use these in module_init()/module_exit()
1320	* and don't forget MODULE_DEVICE_TABLE(usb, ...)
1321	*/
1322	extern int usb_register_driver(struct usb_driver *, struct module *,
1323	const char *);
1324
1325	/* use a define to avoid include chaining to get THIS_MODULE & friends */
1326	#define usb_register(driver) \
1327	usb_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
1328
1329	extern void usb_deregister(struct usb_driver *);
1330
1331	/**
1332	* module_usb_driver() - Helper macro for registering a USB driver
1333	* @__usb_driver: usb_driver struct
1334	*
1335	* Helper macro for USB drivers which do not do anything special in module
1336	* init/exit. This eliminates a lot of boilerplate. Each module may only
1337	* use this macro once, and calling it replaces module_init() and module_exit()
1338	*/
1339	#define module_usb_driver(__usb_driver) \
1340	module_driver(__usb_driver, usb_register, \
1341	usb_deregister)
1342
1343	extern int usb_register_device_driver(struct usb_device_driver *,
1344	struct module *);
1345	extern void usb_deregister_device_driver(struct usb_device_driver *);
1346
1347	extern int usb_register_dev(struct usb_interface *intf,
1348	struct usb_class_driver *class_driver);
1349	extern void usb_deregister_dev(struct usb_interface *intf,
1350	struct usb_class_driver *class_driver);
1351
1352	extern int usb_disabled(void);
1353
1354	/* ----------------------------------------------------------------------- */
1355
1356	/*
1357	* URB support, for asynchronous request completions
1358	*/
1359
1360	/*
1361	* urb->transfer_flags:
1362	*
1363	* Note: URB_DIR_IN/OUT is automatically set in usb_submit_urb().
1364	*/
1365	#define URB_SHORT_NOT_OK 0x0001 /* report short reads as errors */
1366	#define URB_ISO_ASAP 0x0002 /* iso-only; use the first unexpired
1367	* slot in the schedule */
1368	#define URB_NO_TRANSFER_DMA_MAP 0x0004 /* urb->transfer_dma valid on submit */
1369	#define URB_ZERO_PACKET 0x0040 /* Finish bulk OUT with short packet */
1370	#define URB_NO_INTERRUPT 0x0080 /* HINT: no non-error interrupt
1371	* needed */
1372	#define URB_FREE_BUFFER 0x0100 /* Free transfer buffer with the URB */
1373
1374	/* The following flags are used internally by usbcore and HCDs */
1375	#define URB_DIR_IN 0x0200 /* Transfer from device to host */
1376	#define URB_DIR_OUT 0
1377	#define URB_DIR_MASK URB_DIR_IN
1378
1379	#define URB_DMA_MAP_SINGLE 0x00010000 /* Non-scatter-gather mapping */
1380	#define URB_DMA_MAP_PAGE 0x00020000 /* HCD-unsupported S-G */
1381	#define URB_DMA_MAP_SG 0x00040000 /* HCD-supported S-G */
1382	#define URB_MAP_LOCAL 0x00080000 /* HCD-local-memory mapping */
1383	#define URB_SETUP_MAP_SINGLE 0x00100000 /* Setup packet DMA mapped */
1384	#define URB_SETUP_MAP_LOCAL 0x00200000 /* HCD-local setup packet */
1385	#define URB_DMA_SG_COMBINED 0x00400000 /* S-G entries were combined */
1386	#define URB_ALIGNED_TEMP_BUFFER 0x00800000 /* Temp buffer was alloc'd */
1387
1388	struct usb_iso_packet_descriptor {
1389	unsigned int offset;
1390	unsigned int length; /* expected length */
1391	unsigned int actual_length;
1392	int status;
1393	};
1394
1395	struct urb;
1396
1397	struct usb_anchor {
1398	struct list_head urb_list;
1399	wait_queue_head_t wait;
1400	spinlock_t lock;
1401	atomic_t suspend_wakeups;
1402	unsigned int poisoned:1;
1403	};
1404
1405	static inline void init_usb_anchor(struct usb_anchor *anchor)
1406	{
1407	memset(anchor, 0, sizeof(*anchor));
1408	INIT_LIST_HEAD(list: &anchor->urb_list);
1409	init_waitqueue_head(&anchor->wait);
1410	spin_lock_init(&anchor->lock);
1411	}
1412
1413	typedef void (*usb_complete_t)(struct urb *);
1414
1415	/**
1416	* struct urb - USB Request Block
1417	* @urb_list: For use by current owner of the URB.
1418	* @anchor_list: membership in the list of an anchor
1419	* @anchor: to anchor URBs to a common mooring
1420	* @ep: Points to the endpoint's data structure. Will eventually
1421	* replace @pipe.
1422	* @pipe: Holds endpoint number, direction, type, and more.
1423	* Create these values with the eight macros available;
1424	* usb_{snd,rcv}TYPEpipe(dev,endpoint), where the TYPE is "ctrl"
1425	* (control), "bulk", "int" (interrupt), or "iso" (isochronous).
1426	* For example usb_sndbulkpipe() or usb_rcvintpipe(). Endpoint
1427	* numbers range from zero to fifteen. Note that "in" endpoint two
1428	* is a different endpoint (and pipe) from "out" endpoint two.
1429	* The current configuration controls the existence, type, and
1430	* maximum packet size of any given endpoint.
1431	* @stream_id: the endpoint's stream ID for bulk streams
1432	* @dev: Identifies the USB device to perform the request.
1433	* @status: This is read in non-iso completion functions to get the
1434	* status of the particular request. ISO requests only use it
1435	* to tell whether the URB was unlinked; detailed status for
1436	* each frame is in the fields of the iso_frame-desc.
1437	* @transfer_flags: A variety of flags may be used to affect how URB
1438	* submission, unlinking, or operation are handled. Different
1439	* kinds of URB can use different flags.
1440	* @transfer_buffer: This identifies the buffer to (or from) which the I/O
1441	* request will be performed unless URB_NO_TRANSFER_DMA_MAP is set
1442	* (however, do not leave garbage in transfer_buffer even then).
1443	* This buffer must be suitable for DMA; allocate it with
1444	* kmalloc() or equivalent. For transfers to "in" endpoints, contents
1445	* of this buffer will be modified. This buffer is used for the data
1446	* stage of control transfers.
1447	* @transfer_dma: When transfer_flags includes URB_NO_TRANSFER_DMA_MAP,
1448	* the device driver is saying that it provided this DMA address,
1449	* which the host controller driver should use in preference to the
1450	* transfer_buffer.
1451	* @sg: scatter gather buffer list, the buffer size of each element in
1452	* the list (except the last) must be divisible by the endpoint's
1453	* max packet size if no_sg_constraint isn't set in 'struct usb_bus'
1454	* @num_mapped_sgs: (internal) number of mapped sg entries
1455	* @num_sgs: number of entries in the sg list
1456	* @transfer_buffer_length: How big is transfer_buffer. The transfer may
1457	* be broken up into chunks according to the current maximum packet
1458	* size for the endpoint, which is a function of the configuration
1459	* and is encoded in the pipe. When the length is zero, neither
1460	* transfer_buffer nor transfer_dma is used.
1461	* @actual_length: This is read in non-iso completion functions, and
1462	* it tells how many bytes (out of transfer_buffer_length) were
1463	* transferred. It will normally be the same as requested, unless
1464	* either an error was reported or a short read was performed.
1465	* The URB_SHORT_NOT_OK transfer flag may be used to make such
1466	* short reads be reported as errors.
1467	* @setup_packet: Only used for control transfers, this points to eight bytes
1468	* of setup data. Control transfers always start by sending this data
1469	* to the device. Then transfer_buffer is read or written, if needed.
1470	* @setup_dma: DMA pointer for the setup packet. The caller must not use
1471	* this field; setup_packet must point to a valid buffer.
1472	* @start_frame: Returns the initial frame for isochronous transfers.
1473	* @number_of_packets: Lists the number of ISO transfer buffers.
1474	* @interval: Specifies the polling interval for interrupt or isochronous
1475	* transfers. The units are frames (milliseconds) for full and low
1476	* speed devices, and microframes (1/8 millisecond) for highspeed
1477	* and SuperSpeed devices.
1478	* @error_count: Returns the number of ISO transfers that reported errors.
1479	* @context: For use in completion functions. This normally points to
1480	* request-specific driver context.
1481	* @complete: Completion handler. This URB is passed as the parameter to the
1482	* completion function. The completion function may then do what
1483	* it likes with the URB, including resubmitting or freeing it.
1484	* @iso_frame_desc: Used to provide arrays of ISO transfer buffers and to
1485	* collect the transfer status for each buffer.
1486	*
1487	* This structure identifies USB transfer requests. URBs must be allocated by
1488	* calling usb_alloc_urb() and freed with a call to usb_free_urb().
1489	* Initialization may be done using various usb_fill_*_urb() functions. URBs
1490	* are submitted using usb_submit_urb(), and pending requests may be canceled
1491	* using usb_unlink_urb() or usb_kill_urb().
1492	*
1493	* Data Transfer Buffers:
1494	*
1495	* Normally drivers provide I/O buffers allocated with kmalloc() or otherwise
1496	* taken from the general page pool. That is provided by transfer_buffer
1497	* (control requests also use setup_packet), and host controller drivers
1498	* perform a dma mapping (and unmapping) for each buffer transferred. Those
1499	* mapping operations can be expensive on some platforms (perhaps using a dma
1500	* bounce buffer or talking to an IOMMU),
1501	* although they're cheap on commodity x86 and ppc hardware.
1502	*
1503	* Alternatively, drivers may pass the URB_NO_TRANSFER_DMA_MAP transfer flag,
1504	* which tells the host controller driver that no such mapping is needed for
1505	* the transfer_buffer since
1506	* the device driver is DMA-aware. For example, a device driver might
1507	* allocate a DMA buffer with usb_alloc_coherent() or call usb_buffer_map().
1508	* When this transfer flag is provided, host controller drivers will
1509	* attempt to use the dma address found in the transfer_dma
1510	* field rather than determining a dma address themselves.
1511	*
1512	* Note that transfer_buffer must still be set if the controller
1513	* does not support DMA (as indicated by hcd_uses_dma()) and when talking
1514	* to root hub. If you have to transfer between highmem zone and the device
1515	* on such controller, create a bounce buffer or bail out with an error.
1516	* If transfer_buffer cannot be set (is in highmem) and the controller is DMA
1517	* capable, assign NULL to it, so that usbmon knows not to use the value.
1518	* The setup_packet must always be set, so it cannot be located in highmem.
1519	*
1520	* Initialization:
1521	*
1522	* All URBs submitted must initialize the dev, pipe, transfer_flags (may be
1523	* zero), and complete fields. All URBs must also initialize
1524	* transfer_buffer and transfer_buffer_length. They may provide the
1525	* URB_SHORT_NOT_OK transfer flag, indicating that short reads are
1526	* to be treated as errors; that flag is invalid for write requests.
1527	*
1528	* Bulk URBs may
1529	* use the URB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers
1530	* should always terminate with a short packet, even if it means adding an
1531	* extra zero length packet.
1532	*
1533	* Control URBs must provide a valid pointer in the setup_packet field.
1534	* Unlike the transfer_buffer, the setup_packet may not be mapped for DMA
1535	* beforehand.
1536	*
1537	* Interrupt URBs must provide an interval, saying how often (in milliseconds
1538	* or, for highspeed devices, 125 microsecond units)
1539	* to poll for transfers. After the URB has been submitted, the interval
1540	* field reflects how the transfer was actually scheduled.
1541	* The polling interval may be more frequent than requested.
1542	* For example, some controllers have a maximum interval of 32 milliseconds,
1543	* while others support intervals of up to 1024 milliseconds.
1544	* Isochronous URBs also have transfer intervals. (Note that for isochronous
1545	* endpoints, as well as high speed interrupt endpoints, the encoding of
1546	* the transfer interval in the endpoint descriptor is logarithmic.
1547	* Device drivers must convert that value to linear units themselves.)
1548	*
1549	* If an isochronous endpoint queue isn't already running, the host
1550	* controller will schedule a new URB to start as soon as bandwidth
1551	* utilization allows. If the queue is running then a new URB will be
1552	* scheduled to start in the first transfer slot following the end of the
1553	* preceding URB, if that slot has not already expired. If the slot has
1554	* expired (which can happen when IRQ delivery is delayed for a long time),
1555	* the scheduling behavior depends on the URB_ISO_ASAP flag. If the flag
1556	* is clear then the URB will be scheduled to start in the expired slot,
1557	* implying that some of its packets will not be transferred; if the flag
1558	* is set then the URB will be scheduled in the first unexpired slot,
1559	* breaking the queue's synchronization. Upon URB completion, the
1560	* start_frame field will be set to the (micro)frame number in which the
1561	* transfer was scheduled. Ranges for frame counter values are HC-specific
1562	* and can go from as low as 256 to as high as 65536 frames.
1563	*
1564	* Isochronous URBs have a different data transfer model, in part because
1565	* the quality of service is only "best effort". Callers provide specially
1566	* allocated URBs, with number_of_packets worth of iso_frame_desc structures
1567	* at the end. Each such packet is an individual ISO transfer. Isochronous
1568	* URBs are normally queued, submitted by drivers to arrange that
1569	* transfers are at least double buffered, and then explicitly resubmitted
1570	* in completion handlers, so
1571	* that data (such as audio or video) streams at as constant a rate as the
1572	* host controller scheduler can support.
1573	*
1574	* Completion Callbacks:
1575	*
1576	* The completion callback is made in_interrupt(), and one of the first
1577	* things that a completion handler should do is check the status field.
1578	* The status field is provided for all URBs. It is used to report
1579	* unlinked URBs, and status for all non-ISO transfers. It should not
1580	* be examined before the URB is returned to the completion handler.
1581	*
1582	* The context field is normally used to link URBs back to the relevant
1583	* driver or request state.
1584	*
1585	* When the completion callback is invoked for non-isochronous URBs, the
1586	* actual_length field tells how many bytes were transferred. This field
1587	* is updated even when the URB terminated with an error or was unlinked.
1588	*
1589	* ISO transfer status is reported in the status and actual_length fields
1590	* of the iso_frame_desc array, and the number of errors is reported in
1591	* error_count. Completion callbacks for ISO transfers will normally
1592	* (re)submit URBs to ensure a constant transfer rate.
1593	*
1594	* Note that even fields marked "public" should not be touched by the driver
1595	* when the urb is owned by the hcd, that is, since the call to
1596	* usb_submit_urb() till the entry into the completion routine.
1597	*/
1598	struct urb {
1599	/* private: usb core and host controller only fields in the urb */
1600	struct kref kref; /* reference count of the URB */
1601	int unlinked; /* unlink error code */
1602	void *hcpriv; /* private data for host controller */
1603	atomic_t use_count; /* concurrent submissions counter */
1604	atomic_t reject; /* submissions will fail */
1605
1606	/* public: documented fields in the urb that can be used by drivers */
1607	struct list_head urb_list; /* list head for use by the urb's
1608	* current owner */
1609	struct list_head anchor_list; /* the URB may be anchored */
1610	struct usb_anchor *anchor;
1611	struct usb_device *dev; /* (in) pointer to associated device */
1612	struct usb_host_endpoint *ep; /* (internal) pointer to endpoint */
1613	unsigned int pipe; /* (in) pipe information */
1614	unsigned int stream_id; /* (in) stream ID */
1615	int status; /* (return) non-ISO status */
1616	unsigned int transfer_flags; /* (in) URB_SHORT_NOT_OK | ...*/
1617	void *transfer_buffer; /* (in) associated data buffer */
1618	dma_addr_t transfer_dma; /* (in) dma addr for transfer_buffer */
1619	struct scatterlist *sg; /* (in) scatter gather buffer list */
1620	int num_mapped_sgs; /* (internal) mapped sg entries */
1621	int num_sgs; /* (in) number of entries in the sg list */
1622	u32 transfer_buffer_length; /* (in) data buffer length */
1623	u32 actual_length; /* (return) actual transfer length */
1624	unsigned char *setup_packet; /* (in) setup packet (control only) */
1625	dma_addr_t setup_dma; /* (in) dma addr for setup_packet */
1626	int start_frame; /* (modify) start frame (ISO) */
1627	int number_of_packets; /* (in) number of ISO packets */
1628	int interval; /* (modify) transfer interval
1629	* (INT/ISO) */
1630	int error_count; /* (return) number of ISO errors */
1631	void *context; /* (in) context for completion */
1632	usb_complete_t complete; /* (in) completion routine */
1633	struct usb_iso_packet_descriptor iso_frame_desc[];
1634	/* (in) ISO ONLY */
1635	};
1636
1637	/* ----------------------------------------------------------------------- */
1638
1639	/**
1640	* usb_fill_control_urb - initializes a control urb
1641	* @urb: pointer to the urb to initialize.
1642	* @dev: pointer to the struct usb_device for this urb.
1643	* @pipe: the endpoint pipe
1644	* @setup_packet: pointer to the setup_packet buffer. The buffer must be
1645	* suitable for DMA.
1646	* @transfer_buffer: pointer to the transfer buffer. The buffer must be
1647	* suitable for DMA.
1648	* @buffer_length: length of the transfer buffer
1649	* @complete_fn: pointer to the usb_complete_t function
1650	* @context: what to set the urb context to.
1651	*
1652	* Initializes a control urb with the proper information needed to submit
1653	* it to a device.
1654	*
1655	* The transfer buffer and the setup_packet buffer will most likely be filled
1656	* or read via DMA. The simplest way to get a buffer that can be DMAed to is
1657	* allocating it via kmalloc() or equivalent, even for very small buffers.
1658	* If the buffers are embedded in a bigger structure, there is a risk that
1659	* the buffer itself, the previous fields and/or the next fields are corrupted
1660	* due to cache incoherencies; or slowed down if they are evicted from the
1661	* cache. For more information, check &struct urb.
1662	*
1663	*/
1664	static inline void usb_fill_control_urb(struct urb *urb,
1665	struct usb_device *dev,
1666	unsigned int pipe,
1667	unsigned char *setup_packet,
1668	void *transfer_buffer,
1669	int buffer_length,
1670	usb_complete_t complete_fn,
1671	void *context)
1672	{
1673	urb->dev = dev;
1674	urb->pipe = pipe;
1675	urb->setup_packet = setup_packet;
1676	urb->transfer_buffer = transfer_buffer;
1677	urb->transfer_buffer_length = buffer_length;
1678	urb->complete = complete_fn;
1679	urb->context = context;
1680	}
1681
1682	/**
1683	* usb_fill_bulk_urb - macro to help initialize a bulk urb
1684	* @urb: pointer to the urb to initialize.
1685	* @dev: pointer to the struct usb_device for this urb.
1686	* @pipe: the endpoint pipe
1687	* @transfer_buffer: pointer to the transfer buffer. The buffer must be
1688	* suitable for DMA.
1689	* @buffer_length: length of the transfer buffer
1690	* @complete_fn: pointer to the usb_complete_t function
1691	* @context: what to set the urb context to.
1692	*
1693	* Initializes a bulk urb with the proper information needed to submit it
1694	* to a device.
1695	*
1696	* Refer to usb_fill_control_urb() for a description of the requirements for
1697	* transfer_buffer.
1698	*/
1699	static inline void usb_fill_bulk_urb(struct urb *urb,
1700	struct usb_device *dev,
1701	unsigned int pipe,
1702	void *transfer_buffer,
1703	int buffer_length,
1704	usb_complete_t complete_fn,
1705	void *context)
1706	{
1707	urb->dev = dev;
1708	urb->pipe = pipe;
1709	urb->transfer_buffer = transfer_buffer;
1710	urb->transfer_buffer_length = buffer_length;
1711	urb->complete = complete_fn;
1712	urb->context = context;
1713	}
1714
1715	/**
1716	* usb_fill_int_urb - macro to help initialize a interrupt urb
1717	* @urb: pointer to the urb to initialize.
1718	* @dev: pointer to the struct usb_device for this urb.
1719	* @pipe: the endpoint pipe
1720	* @transfer_buffer: pointer to the transfer buffer. The buffer must be
1721	* suitable for DMA.
1722	* @buffer_length: length of the transfer buffer
1723	* @complete_fn: pointer to the usb_complete_t function
1724	* @context: what to set the urb context to.
1725	* @interval: what to set the urb interval to, encoded like
1726	* the endpoint descriptor's bInterval value.
1727	*
1728	* Initializes a interrupt urb with the proper information needed to submit
1729	* it to a device.
1730	*
1731	* Refer to usb_fill_control_urb() for a description of the requirements for
1732	* transfer_buffer.
1733	*
1734	* Note that High Speed and SuperSpeed(+) interrupt endpoints use a logarithmic
1735	* encoding of the endpoint interval, and express polling intervals in
1736	* microframes (eight per millisecond) rather than in frames (one per
1737	* millisecond).
1738	*/
1739	static inline void usb_fill_int_urb(struct urb *urb,
1740	struct usb_device *dev,
1741	unsigned int pipe,
1742	void *transfer_buffer,
1743	int buffer_length,
1744	usb_complete_t complete_fn,
1745	void *context,
1746	int interval)
1747	{
1748	urb->dev = dev;
1749	urb->pipe = pipe;
1750	urb->transfer_buffer = transfer_buffer;
1751	urb->transfer_buffer_length = buffer_length;
1752	urb->complete = complete_fn;
1753	urb->context = context;
1754
1755	if (dev->speed == USB_SPEED_HIGH || dev->speed >= USB_SPEED_SUPER) {
1756	/* make sure interval is within allowed range */
1757	interval = clamp(interval, 1, 16);
1758
1759	urb->interval = 1 << (interval - 1);
1760	} else {
1761	urb->interval = interval;
1762	}
1763
1764	urb->start_frame = -1;
1765	}
1766
1767	extern void usb_init_urb(struct urb *urb);
1768	extern struct urb *usb_alloc_urb(int iso_packets, gfp_t mem_flags);
1769	extern void usb_free_urb(struct urb *urb);
1770	#define usb_put_urb usb_free_urb
1771	extern struct urb *usb_get_urb(struct urb *urb);
1772	extern int usb_submit_urb(struct urb *urb, gfp_t mem_flags);
1773	extern int usb_unlink_urb(struct urb *urb);
1774	extern void usb_kill_urb(struct urb *urb);
1775	extern void usb_poison_urb(struct urb *urb);
1776	extern void usb_unpoison_urb(struct urb *urb);
1777	extern void usb_block_urb(struct urb *urb);
1778	extern void usb_kill_anchored_urbs(struct usb_anchor *anchor);
1779	extern void usb_poison_anchored_urbs(struct usb_anchor *anchor);
1780	extern void usb_unpoison_anchored_urbs(struct usb_anchor *anchor);
1781	extern void usb_unlink_anchored_urbs(struct usb_anchor *anchor);
1782	extern void usb_anchor_suspend_wakeups(struct usb_anchor *anchor);
1783	extern void usb_anchor_resume_wakeups(struct usb_anchor *anchor);
1784	extern void usb_anchor_urb(struct urb *urb, struct usb_anchor *anchor);
1785	extern void usb_unanchor_urb(struct urb *urb);
1786	extern int usb_wait_anchor_empty_timeout(struct usb_anchor *anchor,
1787	unsigned int timeout);
1788	extern struct urb *usb_get_from_anchor(struct usb_anchor *anchor);
1789	extern void usb_scuttle_anchored_urbs(struct usb_anchor *anchor);
1790	extern int usb_anchor_empty(struct usb_anchor *anchor);
1791
1792	#define usb_unblock_urb usb_unpoison_urb
1793
1794	/**
1795	* usb_urb_dir_in - check if an URB describes an IN transfer
1796	* @urb: URB to be checked
1797	*
1798	* Return: 1 if @urb describes an IN transfer (device-to-host),
1799	* otherwise 0.
1800	*/
1801	static inline int usb_urb_dir_in(struct urb *urb)
1802	{
1803	return (urb->transfer_flags & URB_DIR_MASK) == URB_DIR_IN;
1804	}
1805
1806	/**
1807	* usb_urb_dir_out - check if an URB describes an OUT transfer
1808	* @urb: URB to be checked
1809	*
1810	* Return: 1 if @urb describes an OUT transfer (host-to-device),
1811	* otherwise 0.
1812	*/
1813	static inline int usb_urb_dir_out(struct urb *urb)
1814	{
1815	return (urb->transfer_flags & URB_DIR_MASK) == URB_DIR_OUT;
1816	}
1817
1818	int usb_pipe_type_check(struct usb_device *dev, unsigned int pipe);
1819	int usb_urb_ep_type_check(const struct urb *urb);
1820
1821	void *usb_alloc_coherent(struct usb_device *dev, size_t size,
1822	gfp_t mem_flags, dma_addr_t *dma);
1823	void usb_free_coherent(struct usb_device *dev, size_t size,
1824	void *addr, dma_addr_t dma);
1825
1826	/*-------------------------------------------------------------------*
1827	* SYNCHRONOUS CALL SUPPORT *
1828	*-------------------------------------------------------------------*/
1829
1830	extern int usb_control_msg(struct usb_device *dev, unsigned int pipe,
1831	__u8 request, __u8 requesttype, __u16 value, __u16 index,
1832	void *data, __u16 size, int timeout);
1833	extern int usb_interrupt_msg(struct usb_device *usb_dev, unsigned int pipe,
1834	void *data, int len, int *actual_length, int timeout);
1835	extern int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
1836	void *data, int len, int *actual_length,
1837	int timeout);
1838
1839	/* wrappers around usb_control_msg() for the most common standard requests */
1840	int usb_control_msg_send(struct usb_device *dev, __u8 endpoint, __u8 request,
1841	__u8 requesttype, __u16 value, __u16 index,
1842	const void *data, __u16 size, int timeout,
1843	gfp_t memflags);
1844	int usb_control_msg_recv(struct usb_device *dev, __u8 endpoint, __u8 request,
1845	__u8 requesttype, __u16 value, __u16 index,
1846	void *data, __u16 size, int timeout,
1847	gfp_t memflags);
1848	extern int usb_get_descriptor(struct usb_device *dev, unsigned char desctype,
1849	unsigned char descindex, void *buf, int size);
1850	extern int usb_get_status(struct usb_device *dev,
1851	int recip, int type, int target, void *data);
1852
1853	static inline int usb_get_std_status(struct usb_device *dev,
1854	int recip, int target, void *data)
1855	{
1856	return usb_get_status(dev, recip, USB_STATUS_TYPE_STANDARD, target,
1857	data);
1858	}
1859
1860	static inline int usb_get_ptm_status(struct usb_device *dev, void *data)
1861	{
1862	return usb_get_status(dev, USB_RECIP_DEVICE, USB_STATUS_TYPE_PTM,
1863	target: 0, data);
1864	}
1865
1866	extern int usb_string(struct usb_device *dev, int index,
1867	char *buf, size_t size);
1868	extern char *usb_cache_string(struct usb_device *udev, int index);
1869
1870	/* wrappers that also update important state inside usbcore */
1871	extern int usb_clear_halt(struct usb_device *dev, int pipe);
1872	extern int usb_reset_configuration(struct usb_device *dev);
1873	extern int usb_set_interface(struct usb_device *dev, int ifnum, int alternate);
1874	extern void usb_reset_endpoint(struct usb_device *dev, unsigned int epaddr);
1875
1876	/* this request isn't really synchronous, but it belongs with the others */
1877	extern int usb_driver_set_configuration(struct usb_device *udev, int config);
1878
1879	/* choose and set configuration for device */
1880	extern int usb_choose_configuration(struct usb_device *udev);
1881	extern int usb_set_configuration(struct usb_device *dev, int configuration);
1882
1883	/*
1884	* timeouts, in milliseconds, used for sending/receiving control messages
1885	* they typically complete within a few frames (msec) after they're issued
1886	* USB identifies 5 second timeouts, maybe more in a few cases, and a few
1887	* slow devices (like some MGE Ellipse UPSes) actually push that limit.
1888	*/
1889	#define USB_CTRL_GET_TIMEOUT 5000
1890	#define USB_CTRL_SET_TIMEOUT 5000
1891
1892
1893	/**
1894	* struct usb_sg_request - support for scatter/gather I/O
1895	* @status: zero indicates success, else negative errno
1896	* @bytes: counts bytes transferred.
1897	*
1898	* These requests are initialized using usb_sg_init(), and then are used
1899	* as request handles passed to usb_sg_wait() or usb_sg_cancel(). Most
1900	* members of the request object aren't for driver access.
1901	*
1902	* The status and bytecount values are valid only after usb_sg_wait()
1903	* returns. If the status is zero, then the bytecount matches the total
1904	* from the request.
1905	*
1906	* After an error completion, drivers may need to clear a halt condition
1907	* on the endpoint.
1908	*/
1909	struct usb_sg_request {
1910	int status;
1911	size_t bytes;
1912
1913	/* private:
1914	* members below are private to usbcore,
1915	* and are not provided for driver access!
1916	*/
1917	spinlock_t lock;
1918
1919	struct usb_device *dev;
1920	int pipe;
1921
1922	int entries;
1923	struct urb **urbs;
1924
1925	int count;
1926	struct completion complete;
1927	};
1928
1929	int usb_sg_init(
1930	struct usb_sg_request *io,
1931	struct usb_device *dev,
1932	unsigned pipe,
1933	unsigned period,
1934	struct scatterlist *sg,
1935	int nents,
1936	size_t length,
1937	gfp_t mem_flags
1938	);
1939	void usb_sg_cancel(struct usb_sg_request *io);
1940	void usb_sg_wait(struct usb_sg_request *io);
1941
1942
1943	/* ----------------------------------------------------------------------- */
1944
1945	/*
1946	* For various legacy reasons, Linux has a small cookie that's paired with
1947	* a struct usb_device to identify an endpoint queue. Queue characteristics
1948	* are defined by the endpoint's descriptor. This cookie is called a "pipe",
1949	* an unsigned int encoded as:
1950	*
1951	* - direction: bit 7 (0 = Host-to-Device [Out],
1952	* 1 = Device-to-Host [In] ...
1953	* like endpoint bEndpointAddress)
1954	* - device address: bits 8-14 ... bit positions known to uhci-hcd
1955	* - endpoint: bits 15-18 ... bit positions known to uhci-hcd
1956	* - pipe type: bits 30-31 (00 = isochronous, 01 = interrupt,
1957	* 10 = control, 11 = bulk)
1958	*
1959	* Given the device address and endpoint descriptor, pipes are redundant.
1960	*/
1961
1962	/* NOTE: these are not the standard USB_ENDPOINT_XFER_* values!! */
1963	/* (yet ... they're the values used by usbfs) */
1964	#define PIPE_ISOCHRONOUS 0
1965	#define PIPE_INTERRUPT 1
1966	#define PIPE_CONTROL 2
1967	#define PIPE_BULK 3
1968
1969	#define usb_pipein(pipe) ((pipe) & USB_DIR_IN)
1970	#define usb_pipeout(pipe) (!usb_pipein(pipe))
1971
1972	#define usb_pipedevice(pipe) (((pipe) >> 8) & 0x7f)
1973	#define usb_pipeendpoint(pipe) (((pipe) >> 15) & 0xf)
1974
1975	#define usb_pipetype(pipe) (((pipe) >> 30) & 3)
1976	#define usb_pipeisoc(pipe) (usb_pipetype((pipe)) == PIPE_ISOCHRONOUS)
1977	#define usb_pipeint(pipe) (usb_pipetype((pipe)) == PIPE_INTERRUPT)
1978	#define usb_pipecontrol(pipe) (usb_pipetype((pipe)) == PIPE_CONTROL)
1979	#define usb_pipebulk(pipe) (usb_pipetype((pipe)) == PIPE_BULK)
1980
1981	static inline unsigned int __create_pipe(struct usb_device *dev,
1982	unsigned int endpoint)
1983	{
1984	return (dev->devnum << 8) | (endpoint << 15);
1985	}
1986
1987	/* Create various pipes... */
1988	#define usb_sndctrlpipe(dev, endpoint) \
1989	((PIPE_CONTROL << 30) | __create_pipe(dev, endpoint))
1990	#define usb_rcvctrlpipe(dev, endpoint) \
1991	((PIPE_CONTROL << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
1992	#define usb_sndisocpipe(dev, endpoint) \
1993	((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev, endpoint))
1994	#define usb_rcvisocpipe(dev, endpoint) \
1995	((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
1996	#define usb_sndbulkpipe(dev, endpoint) \
1997	((PIPE_BULK << 30) | __create_pipe(dev, endpoint))
1998	#define usb_rcvbulkpipe(dev, endpoint) \
1999	((PIPE_BULK << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
2000	#define usb_sndintpipe(dev, endpoint) \
2001	((PIPE_INTERRUPT << 30) | __create_pipe(dev, endpoint))
2002	#define usb_rcvintpipe(dev, endpoint) \
2003	((PIPE_INTERRUPT << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
2004
2005	static inline struct usb_host_endpoint *
2006	usb_pipe_endpoint(struct usb_device *dev, unsigned int pipe)
2007	{
2008	struct usb_host_endpoint **eps;
2009	eps = usb_pipein(pipe) ? dev->ep_in : dev->ep_out;
2010	return eps[usb_pipeendpoint(pipe)];
2011	}
2012
2013	static inline u16 usb_maxpacket(struct usb_device *udev, int pipe)
2014	{
2015	struct usb_host_endpoint *ep = usb_pipe_endpoint(dev: udev, pipe);
2016
2017	if (!ep)
2018	return 0;
2019
2020	/* NOTE: only 0x07ff bits are for packet size... */
2021	return usb_endpoint_maxp(epd: &ep->desc);
2022	}
2023
2024	/* translate USB error codes to codes user space understands */
2025	static inline int usb_translate_errors(int error_code)
2026	{
2027	switch (error_code) {
2028	case 0:
2029	case -ENOMEM:
2030	case -ENODEV:
2031	case -EOPNOTSUPP:
2032	return error_code;
2033	default:
2034	return -EIO;
2035	}
2036	}
2037
2038	/* Events from the usb core */
2039	#define USB_DEVICE_ADD 0x0001
2040	#define USB_DEVICE_REMOVE 0x0002
2041	#define USB_BUS_ADD 0x0003
2042	#define USB_BUS_REMOVE 0x0004
2043	extern void usb_register_notify(struct notifier_block *nb);
2044	extern void usb_unregister_notify(struct notifier_block *nb);
2045
2046	/* debugfs stuff */
2047	extern struct dentry *usb_debug_root;
2048
2049	/* LED triggers */
2050	enum usb_led_event {
2051	USB_LED_EVENT_HOST = 0,
2052	USB_LED_EVENT_GADGET = 1,
2053	};
2054
2055	#ifdef CONFIG_USB_LED_TRIG
2056	extern void usb_led_activity(enum usb_led_event ev);
2057	#else
2058	static inline void usb_led_activity(enum usb_led_event ev) {}
2059	#endif
2060
2061	#endif /* __KERNEL__ */
2062
2063	#endif
2064