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	* @l1_params: best effor service latency for USB2 L1 LPM state, and L1 timeout.
636	* @u1_params: exit latencies for USB3 U1 LPM state, and hub-initiated timeout.
637	* @u2_params: exit latencies for USB3 U2 LPM state, and hub-initiated timeout.
638	* @lpm_disable_count: Ref count used by usb_disable_lpm() and usb_enable_lpm()
639	* to keep track of the number of functions that require USB 3.0 Link Power
640	* Management to be disabled for this usb_device. This count should only
641	* be manipulated by those functions, with the bandwidth_mutex is held.
642	* @hub_delay: cached value consisting of:
643	* parent->hub_delay + wHubDelay + tTPTransmissionDelay (40ns)
644	* Will be used as wValue for SetIsochDelay requests.
645	* @use_generic_driver: ask driver core to reprobe using the generic driver.
646	*
647	* Notes:
648	* Usbcore drivers should not set usbdev->state directly. Instead use
649	* usb_set_device_state().
650	*/
651	struct usb_device {
652	int devnum;
653	char devpath[16];
654	u32 route;
655	enum usb_device_state state;
656	enum usb_device_speed speed;
657	unsigned int rx_lanes;
658	unsigned int tx_lanes;
659	enum usb_ssp_rate ssp_rate;
660
661	struct usb_tt *tt;
662	int ttport;
663
664	unsigned int toggle[2];
665
666	struct usb_device *parent;
667	struct usb_bus *bus;
668	struct usb_host_endpoint ep0;
669
670	struct device dev;
671
672	struct usb_device_descriptor descriptor;
673	struct usb_host_bos *bos;
674	struct usb_host_config *config;
675
676	struct usb_host_config *actconfig;
677	struct usb_host_endpoint *ep_in[16];
678	struct usb_host_endpoint *ep_out[16];
679
680	char **rawdescriptors;
681
682	unsigned short bus_mA;
683	u8 portnum;
684	u8 level;
685	u8 devaddr;
686
687	unsigned can_submit:1;
688	unsigned persist_enabled:1;
689	unsigned reset_in_progress:1;
690	unsigned have_langid:1;
691	unsigned authorized:1;
692	unsigned authenticated:1;
693	unsigned lpm_capable:1;
694	unsigned lpm_devinit_allow:1;
695	unsigned usb2_hw_lpm_capable:1;
696	unsigned usb2_hw_lpm_besl_capable:1;
697	unsigned usb2_hw_lpm_enabled:1;
698	unsigned usb2_hw_lpm_allowed:1;
699	unsigned usb3_lpm_u1_enabled:1;
700	unsigned usb3_lpm_u2_enabled:1;
701	int string_langid;
702
703	/* static strings from the device */
704	char *product;
705	char *manufacturer;
706	char *serial;
707
708	struct list_head filelist;
709
710	int maxchild;
711
712	u32 quirks;
713	atomic_t urbnum;
714
715	unsigned long active_duration;
716
717	unsigned long connect_time;
718
719	unsigned do_remote_wakeup:1;
720	unsigned reset_resume:1;
721	unsigned port_is_suspended:1;
722
723	int slot_id;
724	struct usb2_lpm_parameters l1_params;
725	struct usb3_lpm_parameters u1_params;
726	struct usb3_lpm_parameters u2_params;
727	unsigned lpm_disable_count;
728
729	u16 hub_delay;
730	unsigned use_generic_driver:1;
731	};
732
733	#define to_usb_device(__dev) container_of_const(__dev, struct usb_device, dev)
734
735	static inline struct usb_device *__intf_to_usbdev(struct usb_interface *intf)
736	{
737	return to_usb_device(intf->dev.parent);
738	}
739	static inline const struct usb_device *__intf_to_usbdev_const(const struct usb_interface *intf)
740	{
741	return to_usb_device((const struct device *)intf->dev.parent);
742	}
743
744	#define interface_to_usbdev(intf) \
745	_Generic((intf), \
746	const struct usb_interface *: __intf_to_usbdev_const, \
747	struct usb_interface *: __intf_to_usbdev)(intf)
748
749	extern struct usb_device *usb_get_dev(struct usb_device *dev);
750	extern void usb_put_dev(struct usb_device *dev);
751	extern struct usb_device *usb_hub_find_child(struct usb_device *hdev,
752	int port1);
753
754	/**
755	* usb_hub_for_each_child - iterate over all child devices on the hub
756	* @hdev: USB device belonging to the usb hub
757	* @port1: portnum associated with child device
758	* @child: child device pointer
759	*/
760	#define usb_hub_for_each_child(hdev, port1, child) \
761	for (port1 = 1, child = usb_hub_find_child(hdev, port1); \
762	port1 <= hdev->maxchild; \
763	child = usb_hub_find_child(hdev, ++port1)) \
764	if (!child) continue; else
765
766	/* USB device locking */
767	#define usb_lock_device(udev) device_lock(&(udev)->dev)
768	#define usb_unlock_device(udev) device_unlock(&(udev)->dev)
769	#define usb_lock_device_interruptible(udev) device_lock_interruptible(&(udev)->dev)
770	#define usb_trylock_device(udev) device_trylock(&(udev)->dev)
771	extern int usb_lock_device_for_reset(struct usb_device *udev,
772	const struct usb_interface *iface);
773
774	/* USB port reset for device reinitialization */
775	extern int usb_reset_device(struct usb_device *dev);
776	extern void usb_queue_reset_device(struct usb_interface *dev);
777
778	extern struct device *usb_intf_get_dma_device(struct usb_interface *intf);
779
780	#ifdef CONFIG_ACPI
781	extern int usb_acpi_set_power_state(struct usb_device *hdev, int index,
782	bool enable);
783	extern bool usb_acpi_power_manageable(struct usb_device *hdev, int index);
784	extern int usb_acpi_port_lpm_incapable(struct usb_device *hdev, int index);
785	#else
786	static inline int usb_acpi_set_power_state(struct usb_device *hdev, int index,
787	bool enable) { return 0; }
788	static inline bool usb_acpi_power_manageable(struct usb_device *hdev, int index)
789	{ return true; }
790	static inline int usb_acpi_port_lpm_incapable(struct usb_device *hdev, int index)
791	{ return 0; }
792	#endif
793
794	/* USB autosuspend and autoresume */
795	#ifdef CONFIG_PM
796	extern void usb_enable_autosuspend(struct usb_device *udev);
797	extern void usb_disable_autosuspend(struct usb_device *udev);
798
799	extern int usb_autopm_get_interface(struct usb_interface *intf);
800	extern void usb_autopm_put_interface(struct usb_interface *intf);
801	extern int usb_autopm_get_interface_async(struct usb_interface *intf);
802	extern void usb_autopm_put_interface_async(struct usb_interface *intf);
803	extern void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
804	extern void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
805
806	static inline void usb_mark_last_busy(struct usb_device *udev)
807	{
808	pm_runtime_mark_last_busy(dev: &udev->dev);
809	}
810
811	#else
812
813	static inline int usb_enable_autosuspend(struct usb_device *udev)
814	{ return 0; }
815	static inline int usb_disable_autosuspend(struct usb_device *udev)
816	{ return 0; }
817
818	static inline int usb_autopm_get_interface(struct usb_interface *intf)
819	{ return 0; }
820	static inline int usb_autopm_get_interface_async(struct usb_interface *intf)
821	{ return 0; }
822
823	static inline void usb_autopm_put_interface(struct usb_interface *intf)
824	{ }
825	static inline void usb_autopm_put_interface_async(struct usb_interface *intf)
826	{ }
827	static inline void usb_autopm_get_interface_no_resume(
828	struct usb_interface *intf)
829	{ }
830	static inline void usb_autopm_put_interface_no_suspend(
831	struct usb_interface *intf)
832	{ }
833	static inline void usb_mark_last_busy(struct usb_device *udev)
834	{ }
835	#endif
836
837	extern int usb_disable_lpm(struct usb_device *udev);
838	extern void usb_enable_lpm(struct usb_device *udev);
839	/* Same as above, but these functions lock/unlock the bandwidth_mutex. */
840	extern int usb_unlocked_disable_lpm(struct usb_device *udev);
841	extern void usb_unlocked_enable_lpm(struct usb_device *udev);
842
843	extern int usb_disable_ltm(struct usb_device *udev);
844	extern void usb_enable_ltm(struct usb_device *udev);
845
846	static inline bool usb_device_supports_ltm(struct usb_device *udev)
847	{
848	if (udev->speed < USB_SPEED_SUPER || !udev->bos || !udev->bos->ss_cap)
849	return false;
850	return udev->bos->ss_cap->bmAttributes & USB_LTM_SUPPORT;
851	}
852
853	static inline bool usb_device_no_sg_constraint(struct usb_device *udev)
854	{
855	return udev && udev->bus && udev->bus->no_sg_constraint;
856	}
857
858
859	/*-------------------------------------------------------------------------*/
860
861	/* for drivers using iso endpoints */
862	extern int usb_get_current_frame_number(struct usb_device *usb_dev);
863
864	/* Sets up a group of bulk endpoints to support multiple stream IDs. */
865	extern int usb_alloc_streams(struct usb_interface *interface,
866	struct usb_host_endpoint **eps, unsigned int num_eps,
867	unsigned int num_streams, gfp_t mem_flags);
868
869	/* Reverts a group of bulk endpoints back to not using stream IDs. */
870	extern int usb_free_streams(struct usb_interface *interface,
871	struct usb_host_endpoint **eps, unsigned int num_eps,
872	gfp_t mem_flags);
873
874	/* used these for multi-interface device registration */
875	extern int usb_driver_claim_interface(struct usb_driver *driver,
876	struct usb_interface *iface, void *data);
877
878	/**
879	* usb_interface_claimed - returns true iff an interface is claimed
880	* @iface: the interface being checked
881	*
882	* Return: %true (nonzero) iff the interface is claimed, else %false
883	* (zero).
884	*
885	* Note:
886	* Callers must own the driver model's usb bus readlock. So driver
887	* probe() entries don't need extra locking, but other call contexts
888	* may need to explicitly claim that lock.
889	*
890	*/
891	static inline int usb_interface_claimed(struct usb_interface *iface)
892	{
893	return (iface->dev.driver != NULL);
894	}
895
896	extern void usb_driver_release_interface(struct usb_driver *driver,
897	struct usb_interface *iface);
898
899	int usb_set_wireless_status(struct usb_interface *iface,
900	enum usb_wireless_status status);
901
902	const struct usb_device_id *usb_match_id(struct usb_interface *interface,
903	const struct usb_device_id *id);
904	extern int usb_match_one_id(struct usb_interface *interface,
905	const struct usb_device_id *id);
906
907	extern int usb_for_each_dev(void *data, int (*fn)(struct usb_device *, void *));
908	extern struct usb_interface *usb_find_interface(struct usb_driver *drv,
909	int minor);
910	extern struct usb_interface *usb_ifnum_to_if(const struct usb_device *dev,
911	unsigned ifnum);
912	extern struct usb_host_interface *usb_altnum_to_altsetting(
913	const struct usb_interface *intf, unsigned int altnum);
914	extern struct usb_host_interface *usb_find_alt_setting(
915	struct usb_host_config *config,
916	unsigned int iface_num,
917	unsigned int alt_num);
918
919	/* port claiming functions */
920	int usb_hub_claim_port(struct usb_device *hdev, unsigned port1,
921	struct usb_dev_state *owner);
922	int usb_hub_release_port(struct usb_device *hdev, unsigned port1,
923	struct usb_dev_state *owner);
924
925	/**
926	* usb_make_path - returns stable device path in the usb tree
927	* @dev: the device whose path is being constructed
928	* @buf: where to put the string
929	* @size: how big is "buf"?
930	*
931	* Return: Length of the string (> 0) or negative if size was too small.
932	*
933	* Note:
934	* This identifier is intended to be "stable", reflecting physical paths in
935	* hardware such as physical bus addresses for host controllers or ports on
936	* USB hubs. That makes it stay the same until systems are physically
937	* reconfigured, by re-cabling a tree of USB devices or by moving USB host
938	* controllers. Adding and removing devices, including virtual root hubs
939	* in host controller driver modules, does not change these path identifiers;
940	* neither does rebooting or re-enumerating. These are more useful identifiers
941	* than changeable ("unstable") ones like bus numbers or device addresses.
942	*
943	* With a partial exception for devices connected to USB 2.0 root hubs, these
944	* identifiers are also predictable. So long as the device tree isn't changed,
945	* plugging any USB device into a given hub port always gives it the same path.
946	* Because of the use of "companion" controllers, devices connected to ports on
947	* USB 2.0 root hubs (EHCI host controllers) will get one path ID if they are
948	* high speed, and a different one if they are full or low speed.
949	*/
950	static inline int usb_make_path(struct usb_device *dev, char *buf, size_t size)
951	{
952	int actual;
953	actual = snprintf(buf, size, fmt: "usb-%s-%s", dev->bus->bus_name,
954	dev->devpath);
955	return (actual >= (int)size) ? -1 : actual;
956	}
957
958	/*-------------------------------------------------------------------------*/
959
960	#define USB_DEVICE_ID_MATCH_DEVICE \
961	(USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
962	#define USB_DEVICE_ID_MATCH_DEV_RANGE \
963	(USB_DEVICE_ID_MATCH_DEV_LO | USB_DEVICE_ID_MATCH_DEV_HI)
964	#define USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION \
965	(USB_DEVICE_ID_MATCH_DEVICE | USB_DEVICE_ID_MATCH_DEV_RANGE)
966	#define USB_DEVICE_ID_MATCH_DEV_INFO \
967	(USB_DEVICE_ID_MATCH_DEV_CLASS | \
968	USB_DEVICE_ID_MATCH_DEV_SUBCLASS | \
969	USB_DEVICE_ID_MATCH_DEV_PROTOCOL)
970	#define USB_DEVICE_ID_MATCH_INT_INFO \
971	(USB_DEVICE_ID_MATCH_INT_CLASS | \
972	USB_DEVICE_ID_MATCH_INT_SUBCLASS | \
973	USB_DEVICE_ID_MATCH_INT_PROTOCOL)
974
975	/**
976	* USB_DEVICE - macro used to describe a specific usb device
977	* @vend: the 16 bit USB Vendor ID
978	* @prod: the 16 bit USB Product ID
979	*
980	* This macro is used to create a struct usb_device_id that matches a
981	* specific device.
982	*/
983	#define USB_DEVICE(vend, prod) \
984	.match_flags = USB_DEVICE_ID_MATCH_DEVICE, \
985	.idVendor = (vend), \
986	.idProduct = (prod)
987	/**
988	* USB_DEVICE_VER - describe a specific usb device with a version range
989	* @vend: the 16 bit USB Vendor ID
990	* @prod: the 16 bit USB Product ID
991	* @lo: the bcdDevice_lo value
992	* @hi: the bcdDevice_hi value
993	*
994	* This macro is used to create a struct usb_device_id that matches a
995	* specific device, with a version range.
996	*/
997	#define USB_DEVICE_VER(vend, prod, lo, hi) \
998	.match_flags = USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION, \
999	.idVendor = (vend), \
1000	.idProduct = (prod), \
1001	.bcdDevice_lo = (lo), \
1002	.bcdDevice_hi = (hi)
1003
1004	/**
1005	* USB_DEVICE_INTERFACE_CLASS - describe a usb device with a specific interface class
1006	* @vend: the 16 bit USB Vendor ID
1007	* @prod: the 16 bit USB Product ID
1008	* @cl: bInterfaceClass value
1009	*
1010	* This macro is used to create a struct usb_device_id that matches a
1011	* specific interface class of devices.
1012	*/
1013	#define USB_DEVICE_INTERFACE_CLASS(vend, prod, cl) \
1014	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
1015	USB_DEVICE_ID_MATCH_INT_CLASS, \
1016	.idVendor = (vend), \
1017	.idProduct = (prod), \
1018	.bInterfaceClass = (cl)
1019
1020	/**
1021	* USB_DEVICE_INTERFACE_PROTOCOL - describe a usb device with a specific interface protocol
1022	* @vend: the 16 bit USB Vendor ID
1023	* @prod: the 16 bit USB Product ID
1024	* @pr: bInterfaceProtocol value
1025	*
1026	* This macro is used to create a struct usb_device_id that matches a
1027	* specific interface protocol of devices.
1028	*/
1029	#define USB_DEVICE_INTERFACE_PROTOCOL(vend, prod, pr) \
1030	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
1031	USB_DEVICE_ID_MATCH_INT_PROTOCOL, \
1032	.idVendor = (vend), \
1033	.idProduct = (prod), \
1034	.bInterfaceProtocol = (pr)
1035
1036	/**
1037	* USB_DEVICE_INTERFACE_NUMBER - describe a usb device with a specific interface number
1038	* @vend: the 16 bit USB Vendor ID
1039	* @prod: the 16 bit USB Product ID
1040	* @num: bInterfaceNumber value
1041	*
1042	* This macro is used to create a struct usb_device_id that matches a
1043	* specific interface number of devices.
1044	*/
1045	#define USB_DEVICE_INTERFACE_NUMBER(vend, prod, num) \
1046	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
1047	USB_DEVICE_ID_MATCH_INT_NUMBER, \
1048	.idVendor = (vend), \
1049	.idProduct = (prod), \
1050	.bInterfaceNumber = (num)
1051
1052	/**
1053	* USB_DEVICE_INFO - macro used to describe a class of usb devices
1054	* @cl: bDeviceClass value
1055	* @sc: bDeviceSubClass value
1056	* @pr: bDeviceProtocol value
1057	*
1058	* This macro is used to create a struct usb_device_id that matches a
1059	* specific class of devices.
1060	*/
1061	#define USB_DEVICE_INFO(cl, sc, pr) \
1062	.match_flags = USB_DEVICE_ID_MATCH_DEV_INFO, \
1063	.bDeviceClass = (cl), \
1064	.bDeviceSubClass = (sc), \
1065	.bDeviceProtocol = (pr)
1066
1067	/**
1068	* USB_INTERFACE_INFO - macro used to describe a class of usb interfaces
1069	* @cl: bInterfaceClass value
1070	* @sc: bInterfaceSubClass value
1071	* @pr: bInterfaceProtocol value
1072	*
1073	* This macro is used to create a struct usb_device_id that matches a
1074	* specific class of interfaces.
1075	*/
1076	#define USB_INTERFACE_INFO(cl, sc, pr) \
1077	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO, \
1078	.bInterfaceClass = (cl), \
1079	.bInterfaceSubClass = (sc), \
1080	.bInterfaceProtocol = (pr)
1081
1082	/**
1083	* USB_DEVICE_AND_INTERFACE_INFO - describe a specific usb device with a class of usb interfaces
1084	* @vend: the 16 bit USB Vendor ID
1085	* @prod: the 16 bit USB Product ID
1086	* @cl: bInterfaceClass value
1087	* @sc: bInterfaceSubClass value
1088	* @pr: bInterfaceProtocol value
1089	*
1090	* This macro is used to create a struct usb_device_id that matches a
1091	* specific device with a specific class of interfaces.
1092	*
1093	* This is especially useful when explicitly matching devices that have
1094	* vendor specific bDeviceClass values, but standards-compliant interfaces.
1095	*/
1096	#define USB_DEVICE_AND_INTERFACE_INFO(vend, prod, cl, sc, pr) \
1097	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
1098	| USB_DEVICE_ID_MATCH_DEVICE, \
1099	.idVendor = (vend), \
1100	.idProduct = (prod), \
1101	.bInterfaceClass = (cl), \
1102	.bInterfaceSubClass = (sc), \
1103	.bInterfaceProtocol = (pr)
1104
1105	/**
1106	* USB_VENDOR_AND_INTERFACE_INFO - describe a specific usb vendor with a class of usb interfaces
1107	* @vend: the 16 bit USB Vendor ID
1108	* @cl: bInterfaceClass value
1109	* @sc: bInterfaceSubClass value
1110	* @pr: bInterfaceProtocol value
1111	*
1112	* This macro is used to create a struct usb_device_id that matches a
1113	* specific vendor with a specific class of interfaces.
1114	*
1115	* This is especially useful when explicitly matching devices that have
1116	* vendor specific bDeviceClass values, but standards-compliant interfaces.
1117	*/
1118	#define USB_VENDOR_AND_INTERFACE_INFO(vend, cl, sc, pr) \
1119	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
1120	| USB_DEVICE_ID_MATCH_VENDOR, \
1121	.idVendor = (vend), \
1122	.bInterfaceClass = (cl), \
1123	.bInterfaceSubClass = (sc), \
1124	.bInterfaceProtocol = (pr)
1125
1126	/* ----------------------------------------------------------------------- */
1127
1128	/* Stuff for dynamic usb ids */
1129	struct usb_dynids {
1130	spinlock_t lock;
1131	struct list_head list;
1132	};
1133
1134	struct usb_dynid {
1135	struct list_head node;
1136	struct usb_device_id id;
1137	};
1138
1139	extern ssize_t usb_store_new_id(struct usb_dynids *dynids,
1140	const struct usb_device_id *id_table,
1141	struct device_driver *driver,
1142	const char *buf, size_t count);
1143
1144	extern ssize_t usb_show_dynids(struct usb_dynids *dynids, char *buf);
1145
1146	/**
1147	* struct usb_driver - identifies USB interface driver to usbcore
1148	* @name: The driver name should be unique among USB drivers,
1149	* and should normally be the same as the module name.
1150	* @probe: Called to see if the driver is willing to manage a particular
1151	* interface on a device. If it is, probe returns zero and uses
1152	* usb_set_intfdata() to associate driver-specific data with the
1153	* interface. It may also use usb_set_interface() to specify the
1154	* appropriate altsetting. If unwilling to manage the interface,
1155	* return -ENODEV, if genuine IO errors occurred, an appropriate
1156	* negative errno value.
1157	* @disconnect: Called when the interface is no longer accessible, usually
1158	* because its device has been (or is being) disconnected or the
1159	* driver module is being unloaded.
1160	* @unlocked_ioctl: Used for drivers that want to talk to userspace through
1161	* the "usbfs" filesystem. This lets devices provide ways to
1162	* expose information to user space regardless of where they
1163	* do (or don't) show up otherwise in the filesystem.
1164	* @suspend: Called when the device is going to be suspended by the
1165	* system either from system sleep or runtime suspend context. The
1166	* return value will be ignored in system sleep context, so do NOT
1167	* try to continue using the device if suspend fails in this case.
1168	* Instead, let the resume or reset-resume routine recover from
1169	* the failure.
1170	* @resume: Called when the device is being resumed by the system.
1171	* @reset_resume: Called when the suspended device has been reset instead
1172	* of being resumed.
1173	* @pre_reset: Called by usb_reset_device() when the device is about to be
1174	* reset. This routine must not return until the driver has no active
1175	* URBs for the device, and no more URBs may be submitted until the
1176	* post_reset method is called.
1177	* @post_reset: Called by usb_reset_device() after the device
1178	* has been reset
1179	* @id_table: USB drivers use ID table to support hotplugging.
1180	* Export this with MODULE_DEVICE_TABLE(usb,...). This must be set
1181	* or your driver's probe function will never get called.
1182	* @dev_groups: Attributes attached to the device that will be created once it
1183	* is bound to the driver.
1184	* @dynids: used internally to hold the list of dynamically added device
1185	* ids for this driver.
1186	* @driver: The driver-model core driver structure.
1187	* @no_dynamic_id: if set to 1, the USB core will not allow dynamic ids to be
1188	* added to this driver by preventing the sysfs file from being created.
1189	* @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
1190	* for interfaces bound to this driver.
1191	* @soft_unbind: if set to 1, the USB core will not kill URBs and disable
1192	* endpoints before calling the driver's disconnect method.
1193	* @disable_hub_initiated_lpm: if set to 1, the USB core will not allow hubs
1194	* to initiate lower power link state transitions when an idle timeout
1195	* occurs. Device-initiated USB 3.0 link PM will still be allowed.
1196	*
1197	* USB interface drivers must provide a name, probe() and disconnect()
1198	* methods, and an id_table. Other driver fields are optional.
1199	*
1200	* The id_table is used in hotplugging. It holds a set of descriptors,
1201	* and specialized data may be associated with each entry. That table
1202	* is used by both user and kernel mode hotplugging support.
1203	*
1204	* The probe() and disconnect() methods are called in a context where
1205	* they can sleep, but they should avoid abusing the privilege. Most
1206	* work to connect to a device should be done when the device is opened,
1207	* and undone at the last close. The disconnect code needs to address
1208	* concurrency issues with respect to open() and close() methods, as
1209	* well as forcing all pending I/O requests to complete (by unlinking
1210	* them as necessary, and blocking until the unlinks complete).
1211	*/
1212	struct usb_driver {
1213	const char *name;
1214
1215	int (*probe) (struct usb_interface *intf,
1216	const struct usb_device_id *id);
1217
1218	void (*disconnect) (struct usb_interface *intf);
1219
1220	int (*unlocked_ioctl) (struct usb_interface *intf, unsigned int code,
1221	void *buf);
1222
1223	int (*suspend) (struct usb_interface *intf, pm_message_t message);
1224	int (*resume) (struct usb_interface *intf);
1225	int (*reset_resume)(struct usb_interface *intf);
1226
1227	int (*pre_reset)(struct usb_interface *intf);
1228	int (*post_reset)(struct usb_interface *intf);
1229
1230	const struct usb_device_id *id_table;
1231	const struct attribute_group **dev_groups;
1232
1233	struct usb_dynids dynids;
1234	struct device_driver driver;
1235	unsigned int no_dynamic_id:1;
1236	unsigned int supports_autosuspend:1;
1237	unsigned int disable_hub_initiated_lpm:1;
1238	unsigned int soft_unbind:1;
1239	};
1240	#define to_usb_driver(d) container_of(d, struct usb_driver, driver)
1241
1242	/**
1243	* struct usb_device_driver - identifies USB device driver to usbcore
1244	* @name: The driver name should be unique among USB drivers,
1245	* and should normally be the same as the module name.
1246	* @match: If set, used for better device/driver matching.
1247	* @probe: Called to see if the driver is willing to manage a particular
1248	* device. If it is, probe returns zero and uses dev_set_drvdata()
1249	* to associate driver-specific data with the device. If unwilling
1250	* to manage the device, return a negative errno value.
1251	* @disconnect: Called when the device is no longer accessible, usually
1252	* because it has been (or is being) disconnected or the driver's
1253	* module is being unloaded.
1254	* @suspend: Called when the device is going to be suspended by the system.
1255	* @resume: Called when the device is being resumed by the system.
1256	* @choose_configuration: If non-NULL, called instead of the default
1257	* usb_choose_configuration(). If this returns an error then we'll go
1258	* on to call the normal usb_choose_configuration().
1259	* @dev_groups: Attributes attached to the device that will be created once it
1260	* is bound to the driver.
1261	* @driver: The driver-model core driver structure.
1262	* @id_table: used with @match() to select better matching driver at
1263	* probe() time.
1264	* @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
1265	* for devices bound to this driver.
1266	* @generic_subclass: if set to 1, the generic USB driver's probe, disconnect,
1267	* resume and suspend functions will be called in addition to the driver's
1268	* own, so this part of the setup does not need to be replicated.
1269	*
1270	* USB drivers must provide all the fields listed above except driver,
1271	* match, and id_table.
1272	*/
1273	struct usb_device_driver {
1274	const char *name;
1275
1276	bool (*match) (struct usb_device *udev);
1277	int (*probe) (struct usb_device *udev);
1278	void (*disconnect) (struct usb_device *udev);
1279
1280	int (*suspend) (struct usb_device *udev, pm_message_t message);
1281	int (*resume) (struct usb_device *udev, pm_message_t message);
1282
1283	int (*choose_configuration) (struct usb_device *udev);
1284
1285	const struct attribute_group **dev_groups;
1286	struct device_driver driver;
1287	const struct usb_device_id *id_table;
1288	unsigned int supports_autosuspend:1;
1289	unsigned int generic_subclass:1;
1290	};
1291	#define to_usb_device_driver(d) container_of(d, struct usb_device_driver, \
1292	driver)
1293
1294	/**
1295	* struct usb_class_driver - identifies a USB driver that wants to use the USB major number
1296	* @name: the usb class device name for this driver. Will show up in sysfs.
1297	* @devnode: Callback to provide a naming hint for a possible
1298	* device node to create.
1299	* @fops: pointer to the struct file_operations of this driver.
1300	* @minor_base: the start of the minor range for this driver.
1301	*
1302	* This structure is used for the usb_register_dev() and
1303	* usb_deregister_dev() functions, to consolidate a number of the
1304	* parameters used for them.
1305	*/
1306	struct usb_class_driver {
1307	char *name;
1308	char *(*devnode)(const struct device *dev, umode_t *mode);
1309	const struct file_operations *fops;
1310	int minor_base;
1311	};
1312
1313	/*
1314	* use these in module_init()/module_exit()
1315	* and don't forget MODULE_DEVICE_TABLE(usb, ...)
1316	*/
1317	extern int usb_register_driver(struct usb_driver *, struct module *,
1318	const char *);
1319
1320	/* use a define to avoid include chaining to get THIS_MODULE & friends */
1321	#define usb_register(driver) \
1322	usb_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
1323
1324	extern void usb_deregister(struct usb_driver *);
1325
1326	/**
1327	* module_usb_driver() - Helper macro for registering a USB driver
1328	* @__usb_driver: usb_driver struct
1329	*
1330	* Helper macro for USB drivers which do not do anything special in module
1331	* init/exit. This eliminates a lot of boilerplate. Each module may only
1332	* use this macro once, and calling it replaces module_init() and module_exit()
1333	*/
1334	#define module_usb_driver(__usb_driver) \
1335	module_driver(__usb_driver, usb_register, \
1336	usb_deregister)
1337
1338	extern int usb_register_device_driver(struct usb_device_driver *,
1339	struct module *);
1340	extern void usb_deregister_device_driver(struct usb_device_driver *);
1341
1342	extern int usb_register_dev(struct usb_interface *intf,
1343	struct usb_class_driver *class_driver);
1344	extern void usb_deregister_dev(struct usb_interface *intf,
1345	struct usb_class_driver *class_driver);
1346
1347	extern int usb_disabled(void);
1348
1349	/* ----------------------------------------------------------------------- */
1350
1351	/*
1352	* URB support, for asynchronous request completions
1353	*/
1354
1355	/*
1356	* urb->transfer_flags:
1357	*
1358	* Note: URB_DIR_IN/OUT is automatically set in usb_submit_urb().
1359	*/
1360	#define URB_SHORT_NOT_OK 0x0001 /* report short reads as errors */
1361	#define URB_ISO_ASAP 0x0002 /* iso-only; use the first unexpired
1362	* slot in the schedule */
1363	#define URB_NO_TRANSFER_DMA_MAP 0x0004 /* urb->transfer_dma valid on submit */
1364	#define URB_ZERO_PACKET 0x0040 /* Finish bulk OUT with short packet */
1365	#define URB_NO_INTERRUPT 0x0080 /* HINT: no non-error interrupt
1366	* needed */
1367	#define URB_FREE_BUFFER 0x0100 /* Free transfer buffer with the URB */
1368
1369	/* The following flags are used internally by usbcore and HCDs */
1370	#define URB_DIR_IN 0x0200 /* Transfer from device to host */
1371	#define URB_DIR_OUT 0
1372	#define URB_DIR_MASK URB_DIR_IN
1373
1374	#define URB_DMA_MAP_SINGLE 0x00010000 /* Non-scatter-gather mapping */
1375	#define URB_DMA_MAP_PAGE 0x00020000 /* HCD-unsupported S-G */
1376	#define URB_DMA_MAP_SG 0x00040000 /* HCD-supported S-G */
1377	#define URB_MAP_LOCAL 0x00080000 /* HCD-local-memory mapping */
1378	#define URB_SETUP_MAP_SINGLE 0x00100000 /* Setup packet DMA mapped */
1379	#define URB_SETUP_MAP_LOCAL 0x00200000 /* HCD-local setup packet */
1380	#define URB_DMA_SG_COMBINED 0x00400000 /* S-G entries were combined */
1381	#define URB_ALIGNED_TEMP_BUFFER 0x00800000 /* Temp buffer was alloc'd */
1382
1383	struct usb_iso_packet_descriptor {
1384	unsigned int offset;
1385	unsigned int length; /* expected length */
1386	unsigned int actual_length;
1387	int status;
1388	};
1389
1390	struct urb;
1391
1392	struct usb_anchor {
1393	struct list_head urb_list;
1394	wait_queue_head_t wait;
1395	spinlock_t lock;
1396	atomic_t suspend_wakeups;
1397	unsigned int poisoned:1;
1398	};
1399
1400	static inline void init_usb_anchor(struct usb_anchor *anchor)
1401	{
1402	memset(anchor, 0, sizeof(*anchor));
1403	INIT_LIST_HEAD(list: &anchor->urb_list);
1404	init_waitqueue_head(&anchor->wait);
1405	spin_lock_init(&anchor->lock);
1406	}
1407
1408	typedef void (*usb_complete_t)(struct urb *);
1409
1410	/**
1411	* struct urb - USB Request Block
1412	* @urb_list: For use by current owner of the URB.
1413	* @anchor_list: membership in the list of an anchor
1414	* @anchor: to anchor URBs to a common mooring
1415	* @ep: Points to the endpoint's data structure. Will eventually
1416	* replace @pipe.
1417	* @pipe: Holds endpoint number, direction, type, and more.
1418	* Create these values with the eight macros available;
1419	* usb_{snd,rcv}TYPEpipe(dev,endpoint), where the TYPE is "ctrl"
1420	* (control), "bulk", "int" (interrupt), or "iso" (isochronous).
1421	* For example usb_sndbulkpipe() or usb_rcvintpipe(). Endpoint
1422	* numbers range from zero to fifteen. Note that "in" endpoint two
1423	* is a different endpoint (and pipe) from "out" endpoint two.
1424	* The current configuration controls the existence, type, and
1425	* maximum packet size of any given endpoint.
1426	* @stream_id: the endpoint's stream ID for bulk streams
1427	* @dev: Identifies the USB device to perform the request.
1428	* @status: This is read in non-iso completion functions to get the
1429	* status of the particular request. ISO requests only use it
1430	* to tell whether the URB was unlinked; detailed status for
1431	* each frame is in the fields of the iso_frame-desc.
1432	* @transfer_flags: A variety of flags may be used to affect how URB
1433	* submission, unlinking, or operation are handled. Different
1434	* kinds of URB can use different flags.
1435	* @transfer_buffer: This identifies the buffer to (or from) which the I/O
1436	* request will be performed unless URB_NO_TRANSFER_DMA_MAP is set
1437	* (however, do not leave garbage in transfer_buffer even then).
1438	* This buffer must be suitable for DMA; allocate it with
1439	* kmalloc() or equivalent. For transfers to "in" endpoints, contents
1440	* of this buffer will be modified. This buffer is used for the data
1441	* stage of control transfers.
1442	* @transfer_dma: When transfer_flags includes URB_NO_TRANSFER_DMA_MAP,
1443	* the device driver is saying that it provided this DMA address,
1444	* which the host controller driver should use in preference to the
1445	* transfer_buffer.
1446	* @sg: scatter gather buffer list, the buffer size of each element in
1447	* the list (except the last) must be divisible by the endpoint's
1448	* max packet size if no_sg_constraint isn't set in 'struct usb_bus'
1449	* @num_mapped_sgs: (internal) number of mapped sg entries
1450	* @num_sgs: number of entries in the sg list
1451	* @transfer_buffer_length: How big is transfer_buffer. The transfer may
1452	* be broken up into chunks according to the current maximum packet
1453	* size for the endpoint, which is a function of the configuration
1454	* and is encoded in the pipe. When the length is zero, neither
1455	* transfer_buffer nor transfer_dma is used.
1456	* @actual_length: This is read in non-iso completion functions, and
1457	* it tells how many bytes (out of transfer_buffer_length) were
1458	* transferred. It will normally be the same as requested, unless
1459	* either an error was reported or a short read was performed.
1460	* The URB_SHORT_NOT_OK transfer flag may be used to make such
1461	* short reads be reported as errors.
1462	* @setup_packet: Only used for control transfers, this points to eight bytes
1463	* of setup data. Control transfers always start by sending this data
1464	* to the device. Then transfer_buffer is read or written, if needed.
1465	* @setup_dma: DMA pointer for the setup packet. The caller must not use
1466	* this field; setup_packet must point to a valid buffer.
1467	* @start_frame: Returns the initial frame for isochronous transfers.
1468	* @number_of_packets: Lists the number of ISO transfer buffers.
1469	* @interval: Specifies the polling interval for interrupt or isochronous
1470	* transfers. The units are frames (milliseconds) for full and low
1471	* speed devices, and microframes (1/8 millisecond) for highspeed
1472	* and SuperSpeed devices.
1473	* @error_count: Returns the number of ISO transfers that reported errors.
1474	* @context: For use in completion functions. This normally points to
1475	* request-specific driver context.
1476	* @complete: Completion handler. This URB is passed as the parameter to the
1477	* completion function. The completion function may then do what
1478	* it likes with the URB, including resubmitting or freeing it.
1479	* @iso_frame_desc: Used to provide arrays of ISO transfer buffers and to
1480	* collect the transfer status for each buffer.
1481	*
1482	* This structure identifies USB transfer requests. URBs must be allocated by
1483	* calling usb_alloc_urb() and freed with a call to usb_free_urb().
1484	* Initialization may be done using various usb_fill_*_urb() functions. URBs
1485	* are submitted using usb_submit_urb(), and pending requests may be canceled
1486	* using usb_unlink_urb() or usb_kill_urb().
1487	*
1488	* Data Transfer Buffers:
1489	*
1490	* Normally drivers provide I/O buffers allocated with kmalloc() or otherwise
1491	* taken from the general page pool. That is provided by transfer_buffer
1492	* (control requests also use setup_packet), and host controller drivers
1493	* perform a dma mapping (and unmapping) for each buffer transferred. Those
1494	* mapping operations can be expensive on some platforms (perhaps using a dma
1495	* bounce buffer or talking to an IOMMU),
1496	* although they're cheap on commodity x86 and ppc hardware.
1497	*
1498	* Alternatively, drivers may pass the URB_NO_TRANSFER_DMA_MAP transfer flag,
1499	* which tells the host controller driver that no such mapping is needed for
1500	* the transfer_buffer since
1501	* the device driver is DMA-aware. For example, a device driver might
1502	* allocate a DMA buffer with usb_alloc_coherent() or call usb_buffer_map().
1503	* When this transfer flag is provided, host controller drivers will
1504	* attempt to use the dma address found in the transfer_dma
1505	* field rather than determining a dma address themselves.
1506	*
1507	* Note that transfer_buffer must still be set if the controller
1508	* does not support DMA (as indicated by hcd_uses_dma()) and when talking
1509	* to root hub. If you have to transfer between highmem zone and the device
1510	* on such controller, create a bounce buffer or bail out with an error.
1511	* If transfer_buffer cannot be set (is in highmem) and the controller is DMA
1512	* capable, assign NULL to it, so that usbmon knows not to use the value.
1513	* The setup_packet must always be set, so it cannot be located in highmem.
1514	*
1515	* Initialization:
1516	*
1517	* All URBs submitted must initialize the dev, pipe, transfer_flags (may be
1518	* zero), and complete fields. All URBs must also initialize
1519	* transfer_buffer and transfer_buffer_length. They may provide the
1520	* URB_SHORT_NOT_OK transfer flag, indicating that short reads are
1521	* to be treated as errors; that flag is invalid for write requests.
1522	*
1523	* Bulk URBs may
1524	* use the URB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers
1525	* should always terminate with a short packet, even if it means adding an
1526	* extra zero length packet.
1527	*
1528	* Control URBs must provide a valid pointer in the setup_packet field.
1529	* Unlike the transfer_buffer, the setup_packet may not be mapped for DMA
1530	* beforehand.
1531	*
1532	* Interrupt URBs must provide an interval, saying how often (in milliseconds
1533	* or, for highspeed devices, 125 microsecond units)
1534	* to poll for transfers. After the URB has been submitted, the interval
1535	* field reflects how the transfer was actually scheduled.
1536	* The polling interval may be more frequent than requested.
1537	* For example, some controllers have a maximum interval of 32 milliseconds,
1538	* while others support intervals of up to 1024 milliseconds.
1539	* Isochronous URBs also have transfer intervals. (Note that for isochronous
1540	* endpoints, as well as high speed interrupt endpoints, the encoding of
1541	* the transfer interval in the endpoint descriptor is logarithmic.
1542	* Device drivers must convert that value to linear units themselves.)
1543	*
1544	* If an isochronous endpoint queue isn't already running, the host
1545	* controller will schedule a new URB to start as soon as bandwidth
1546	* utilization allows. If the queue is running then a new URB will be
1547	* scheduled to start in the first transfer slot following the end of the
1548	* preceding URB, if that slot has not already expired. If the slot has
1549	* expired (which can happen when IRQ delivery is delayed for a long time),
1550	* the scheduling behavior depends on the URB_ISO_ASAP flag. If the flag
1551	* is clear then the URB will be scheduled to start in the expired slot,
1552	* implying that some of its packets will not be transferred; if the flag
1553	* is set then the URB will be scheduled in the first unexpired slot,
1554	* breaking the queue's synchronization. Upon URB completion, the
1555	* start_frame field will be set to the (micro)frame number in which the
1556	* transfer was scheduled. Ranges for frame counter values are HC-specific
1557	* and can go from as low as 256 to as high as 65536 frames.
1558	*
1559	* Isochronous URBs have a different data transfer model, in part because
1560	* the quality of service is only "best effort". Callers provide specially
1561	* allocated URBs, with number_of_packets worth of iso_frame_desc structures
1562	* at the end. Each such packet is an individual ISO transfer. Isochronous
1563	* URBs are normally queued, submitted by drivers to arrange that
1564	* transfers are at least double buffered, and then explicitly resubmitted
1565	* in completion handlers, so
1566	* that data (such as audio or video) streams at as constant a rate as the
1567	* host controller scheduler can support.
1568	*
1569	* Completion Callbacks:
1570	*
1571	* The completion callback is made in_interrupt(), and one of the first
1572	* things that a completion handler should do is check the status field.
1573	* The status field is provided for all URBs. It is used to report
1574	* unlinked URBs, and status for all non-ISO transfers. It should not
1575	* be examined before the URB is returned to the completion handler.
1576	*
1577	* The context field is normally used to link URBs back to the relevant
1578	* driver or request state.
1579	*
1580	* When the completion callback is invoked for non-isochronous URBs, the
1581	* actual_length field tells how many bytes were transferred. This field
1582	* is updated even when the URB terminated with an error or was unlinked.
1583	*
1584	* ISO transfer status is reported in the status and actual_length fields
1585	* of the iso_frame_desc array, and the number of errors is reported in
1586	* error_count. Completion callbacks for ISO transfers will normally
1587	* (re)submit URBs to ensure a constant transfer rate.
1588	*
1589	* Note that even fields marked "public" should not be touched by the driver
1590	* when the urb is owned by the hcd, that is, since the call to
1591	* usb_submit_urb() till the entry into the completion routine.
1592	*/
1593	struct urb {
1594	/* private: usb core and host controller only fields in the urb */
1595	struct kref kref; /* reference count of the URB */
1596	int unlinked; /* unlink error code */
1597	void *hcpriv; /* private data for host controller */
1598	atomic_t use_count; /* concurrent submissions counter */
1599	atomic_t reject; /* submissions will fail */
1600
1601	/* public: documented fields in the urb that can be used by drivers */
1602	struct list_head urb_list; /* list head for use by the urb's
1603	* current owner */
1604	struct list_head anchor_list; /* the URB may be anchored */
1605	struct usb_anchor *anchor;
1606	struct usb_device *dev; /* (in) pointer to associated device */
1607	struct usb_host_endpoint *ep; /* (internal) pointer to endpoint */
1608	unsigned int pipe; /* (in) pipe information */
1609	unsigned int stream_id; /* (in) stream ID */
1610	int status; /* (return) non-ISO status */
1611	unsigned int transfer_flags; /* (in) URB_SHORT_NOT_OK | ...*/
1612	void *transfer_buffer; /* (in) associated data buffer */
1613	dma_addr_t transfer_dma; /* (in) dma addr for transfer_buffer */
1614	struct scatterlist *sg; /* (in) scatter gather buffer list */
1615	int num_mapped_sgs; /* (internal) mapped sg entries */
1616	int num_sgs; /* (in) number of entries in the sg list */
1617	u32 transfer_buffer_length; /* (in) data buffer length */
1618	u32 actual_length; /* (return) actual transfer length */
1619	unsigned char *setup_packet; /* (in) setup packet (control only) */
1620	dma_addr_t setup_dma; /* (in) dma addr for setup_packet */
1621	int start_frame; /* (modify) start frame (ISO) */
1622	int number_of_packets; /* (in) number of ISO packets */
1623	int interval; /* (modify) transfer interval
1624	* (INT/ISO) */
1625	int error_count; /* (return) number of ISO errors */
1626	void *context; /* (in) context for completion */
1627	usb_complete_t complete; /* (in) completion routine */
1628	struct usb_iso_packet_descriptor iso_frame_desc[];
1629	/* (in) ISO ONLY */
1630	};
1631
1632	/* ----------------------------------------------------------------------- */
1633
1634	/**
1635	* usb_fill_control_urb - initializes a control urb
1636	* @urb: pointer to the urb to initialize.
1637	* @dev: pointer to the struct usb_device for this urb.
1638	* @pipe: the endpoint pipe
1639	* @setup_packet: pointer to the setup_packet buffer. The buffer must be
1640	* suitable for DMA.
1641	* @transfer_buffer: pointer to the transfer buffer. The buffer must be
1642	* suitable for DMA.
1643	* @buffer_length: length of the transfer buffer
1644	* @complete_fn: pointer to the usb_complete_t function
1645	* @context: what to set the urb context to.
1646	*
1647	* Initializes a control urb with the proper information needed to submit
1648	* it to a device.
1649	*
1650	* The transfer buffer and the setup_packet buffer will most likely be filled
1651	* or read via DMA. The simplest way to get a buffer that can be DMAed to is
1652	* allocating it via kmalloc() or equivalent, even for very small buffers.
1653	* If the buffers are embedded in a bigger structure, there is a risk that
1654	* the buffer itself, the previous fields and/or the next fields are corrupted
1655	* due to cache incoherencies; or slowed down if they are evicted from the
1656	* cache. For more information, check &struct urb.
1657	*
1658	*/
1659	static inline void usb_fill_control_urb(struct urb *urb,
1660	struct usb_device *dev,
1661	unsigned int pipe,
1662	unsigned char *setup_packet,
1663	void *transfer_buffer,
1664	int buffer_length,
1665	usb_complete_t complete_fn,
1666	void *context)
1667	{
1668	urb->dev = dev;
1669	urb->pipe = pipe;
1670	urb->setup_packet = setup_packet;
1671	urb->transfer_buffer = transfer_buffer;
1672	urb->transfer_buffer_length = buffer_length;
1673	urb->complete = complete_fn;
1674	urb->context = context;
1675	}
1676
1677	/**
1678	* usb_fill_bulk_urb - macro to help initialize a bulk urb
1679	* @urb: pointer to the urb to initialize.
1680	* @dev: pointer to the struct usb_device for this urb.
1681	* @pipe: the endpoint pipe
1682	* @transfer_buffer: pointer to the transfer buffer. The buffer must be
1683	* suitable for DMA.
1684	* @buffer_length: length of the transfer buffer
1685	* @complete_fn: pointer to the usb_complete_t function
1686	* @context: what to set the urb context to.
1687	*
1688	* Initializes a bulk urb with the proper information needed to submit it
1689	* to a device.
1690	*
1691	* Refer to usb_fill_control_urb() for a description of the requirements for
1692	* transfer_buffer.
1693	*/
1694	static inline void usb_fill_bulk_urb(struct urb *urb,
1695	struct usb_device *dev,
1696	unsigned int pipe,
1697	void *transfer_buffer,
1698	int buffer_length,
1699	usb_complete_t complete_fn,
1700	void *context)
1701	{
1702	urb->dev = dev;
1703	urb->pipe = pipe;
1704	urb->transfer_buffer = transfer_buffer;
1705	urb->transfer_buffer_length = buffer_length;
1706	urb->complete = complete_fn;
1707	urb->context = context;
1708	}
1709
1710	/**
1711	* usb_fill_int_urb - macro to help initialize a interrupt urb
1712	* @urb: pointer to the urb to initialize.
1713	* @dev: pointer to the struct usb_device for this urb.
1714	* @pipe: the endpoint pipe
1715	* @transfer_buffer: pointer to the transfer buffer. The buffer must be
1716	* suitable for DMA.
1717	* @buffer_length: length of the transfer buffer
1718	* @complete_fn: pointer to the usb_complete_t function
1719	* @context: what to set the urb context to.
1720	* @interval: what to set the urb interval to, encoded like
1721	* the endpoint descriptor's bInterval value.
1722	*
1723	* Initializes a interrupt urb with the proper information needed to submit
1724	* it to a device.
1725	*
1726	* Refer to usb_fill_control_urb() for a description of the requirements for
1727	* transfer_buffer.
1728	*
1729	* Note that High Speed and SuperSpeed(+) interrupt endpoints use a logarithmic
1730	* encoding of the endpoint interval, and express polling intervals in
1731	* microframes (eight per millisecond) rather than in frames (one per
1732	* millisecond).
1733	*/
1734	static inline void usb_fill_int_urb(struct urb *urb,
1735	struct usb_device *dev,
1736	unsigned int pipe,
1737	void *transfer_buffer,
1738	int buffer_length,
1739	usb_complete_t complete_fn,
1740	void *context,
1741	int interval)
1742	{
1743	urb->dev = dev;
1744	urb->pipe = pipe;
1745	urb->transfer_buffer = transfer_buffer;
1746	urb->transfer_buffer_length = buffer_length;
1747	urb->complete = complete_fn;
1748	urb->context = context;
1749
1750	if (dev->speed == USB_SPEED_HIGH || dev->speed >= USB_SPEED_SUPER) {
1751	/* make sure interval is within allowed range */
1752	interval = clamp(interval, 1, 16);
1753
1754	urb->interval = 1 << (interval - 1);
1755	} else {
1756	urb->interval = interval;
1757	}
1758
1759	urb->start_frame = -1;
1760	}
1761
1762	extern void usb_init_urb(struct urb *urb);
1763	extern struct urb *usb_alloc_urb(int iso_packets, gfp_t mem_flags);
1764	extern void usb_free_urb(struct urb *urb);
1765	#define usb_put_urb usb_free_urb
1766	extern struct urb *usb_get_urb(struct urb *urb);
1767	extern int usb_submit_urb(struct urb *urb, gfp_t mem_flags);
1768	extern int usb_unlink_urb(struct urb *urb);
1769	extern void usb_kill_urb(struct urb *urb);
1770	extern void usb_poison_urb(struct urb *urb);
1771	extern void usb_unpoison_urb(struct urb *urb);
1772	extern void usb_block_urb(struct urb *urb);
1773	extern void usb_kill_anchored_urbs(struct usb_anchor *anchor);
1774	extern void usb_poison_anchored_urbs(struct usb_anchor *anchor);
1775	extern void usb_unpoison_anchored_urbs(struct usb_anchor *anchor);
1776	extern void usb_unlink_anchored_urbs(struct usb_anchor *anchor);
1777	extern void usb_anchor_suspend_wakeups(struct usb_anchor *anchor);
1778	extern void usb_anchor_resume_wakeups(struct usb_anchor *anchor);
1779	extern void usb_anchor_urb(struct urb *urb, struct usb_anchor *anchor);
1780	extern void usb_unanchor_urb(struct urb *urb);
1781	extern int usb_wait_anchor_empty_timeout(struct usb_anchor *anchor,
1782	unsigned int timeout);
1783	extern struct urb *usb_get_from_anchor(struct usb_anchor *anchor);
1784	extern void usb_scuttle_anchored_urbs(struct usb_anchor *anchor);
1785	extern int usb_anchor_empty(struct usb_anchor *anchor);
1786
1787	#define usb_unblock_urb usb_unpoison_urb
1788
1789	/**
1790	* usb_urb_dir_in - check if an URB describes an IN transfer
1791	* @urb: URB to be checked
1792	*
1793	* Return: 1 if @urb describes an IN transfer (device-to-host),
1794	* otherwise 0.
1795	*/
1796	static inline int usb_urb_dir_in(struct urb *urb)
1797	{
1798	return (urb->transfer_flags & URB_DIR_MASK) == URB_DIR_IN;
1799	}
1800
1801	/**
1802	* usb_urb_dir_out - check if an URB describes an OUT transfer
1803	* @urb: URB to be checked
1804	*
1805	* Return: 1 if @urb describes an OUT transfer (host-to-device),
1806	* otherwise 0.
1807	*/
1808	static inline int usb_urb_dir_out(struct urb *urb)
1809	{
1810	return (urb->transfer_flags & URB_DIR_MASK) == URB_DIR_OUT;
1811	}
1812
1813	int usb_pipe_type_check(struct usb_device *dev, unsigned int pipe);
1814	int usb_urb_ep_type_check(const struct urb *urb);
1815
1816	void *usb_alloc_coherent(struct usb_device *dev, size_t size,
1817	gfp_t mem_flags, dma_addr_t *dma);
1818	void usb_free_coherent(struct usb_device *dev, size_t size,
1819	void *addr, dma_addr_t dma);
1820
1821	/*-------------------------------------------------------------------*
1822	* SYNCHRONOUS CALL SUPPORT *
1823	*-------------------------------------------------------------------*/
1824
1825	extern int usb_control_msg(struct usb_device *dev, unsigned int pipe,
1826	__u8 request, __u8 requesttype, __u16 value, __u16 index,
1827	void *data, __u16 size, int timeout);
1828	extern int usb_interrupt_msg(struct usb_device *usb_dev, unsigned int pipe,
1829	void *data, int len, int *actual_length, int timeout);
1830	extern int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
1831	void *data, int len, int *actual_length,
1832	int timeout);
1833
1834	/* wrappers around usb_control_msg() for the most common standard requests */
1835	int usb_control_msg_send(struct usb_device *dev, __u8 endpoint, __u8 request,
1836	__u8 requesttype, __u16 value, __u16 index,
1837	const void *data, __u16 size, int timeout,
1838	gfp_t memflags);
1839	int usb_control_msg_recv(struct usb_device *dev, __u8 endpoint, __u8 request,
1840	__u8 requesttype, __u16 value, __u16 index,
1841	void *data, __u16 size, int timeout,
1842	gfp_t memflags);
1843	extern int usb_get_descriptor(struct usb_device *dev, unsigned char desctype,
1844	unsigned char descindex, void *buf, int size);
1845	extern int usb_get_status(struct usb_device *dev,
1846	int recip, int type, int target, void *data);
1847
1848	static inline int usb_get_std_status(struct usb_device *dev,
1849	int recip, int target, void *data)
1850	{
1851	return usb_get_status(dev, recip, USB_STATUS_TYPE_STANDARD, target,
1852	data);
1853	}
1854
1855	static inline int usb_get_ptm_status(struct usb_device *dev, void *data)
1856	{
1857	return usb_get_status(dev, USB_RECIP_DEVICE, USB_STATUS_TYPE_PTM,
1858	target: 0, data);
1859	}
1860
1861	extern int usb_string(struct usb_device *dev, int index,
1862	char *buf, size_t size);
1863	extern char *usb_cache_string(struct usb_device *udev, int index);
1864
1865	/* wrappers that also update important state inside usbcore */
1866	extern int usb_clear_halt(struct usb_device *dev, int pipe);
1867	extern int usb_reset_configuration(struct usb_device *dev);
1868	extern int usb_set_interface(struct usb_device *dev, int ifnum, int alternate);
1869	extern void usb_reset_endpoint(struct usb_device *dev, unsigned int epaddr);
1870
1871	/* this request isn't really synchronous, but it belongs with the others */
1872	extern int usb_driver_set_configuration(struct usb_device *udev, int config);
1873
1874	/* choose and set configuration for device */
1875	extern int usb_choose_configuration(struct usb_device *udev);
1876	extern int usb_set_configuration(struct usb_device *dev, int configuration);
1877
1878	/*
1879	* timeouts, in milliseconds, used for sending/receiving control messages
1880	* they typically complete within a few frames (msec) after they're issued
1881	* USB identifies 5 second timeouts, maybe more in a few cases, and a few
1882	* slow devices (like some MGE Ellipse UPSes) actually push that limit.
1883	*/
1884	#define USB_CTRL_GET_TIMEOUT 5000
1885	#define USB_CTRL_SET_TIMEOUT 5000
1886
1887
1888	/**
1889	* struct usb_sg_request - support for scatter/gather I/O
1890	* @status: zero indicates success, else negative errno
1891	* @bytes: counts bytes transferred.
1892	*
1893	* These requests are initialized using usb_sg_init(), and then are used
1894	* as request handles passed to usb_sg_wait() or usb_sg_cancel(). Most
1895	* members of the request object aren't for driver access.
1896	*
1897	* The status and bytecount values are valid only after usb_sg_wait()
1898	* returns. If the status is zero, then the bytecount matches the total
1899	* from the request.
1900	*
1901	* After an error completion, drivers may need to clear a halt condition
1902	* on the endpoint.
1903	*/
1904	struct usb_sg_request {
1905	int status;
1906	size_t bytes;
1907
1908	/* private:
1909	* members below are private to usbcore,
1910	* and are not provided for driver access!
1911	*/
1912	spinlock_t lock;
1913
1914	struct usb_device *dev;
1915	int pipe;
1916
1917	int entries;
1918	struct urb **urbs;
1919
1920	int count;
1921	struct completion complete;
1922	};
1923
1924	int usb_sg_init(
1925	struct usb_sg_request *io,
1926	struct usb_device *dev,
1927	unsigned pipe,
1928	unsigned period,
1929	struct scatterlist *sg,
1930	int nents,
1931	size_t length,
1932	gfp_t mem_flags
1933	);
1934	void usb_sg_cancel(struct usb_sg_request *io);
1935	void usb_sg_wait(struct usb_sg_request *io);
1936
1937
1938	/* ----------------------------------------------------------------------- */
1939
1940	/*
1941	* For various legacy reasons, Linux has a small cookie that's paired with
1942	* a struct usb_device to identify an endpoint queue. Queue characteristics
1943	* are defined by the endpoint's descriptor. This cookie is called a "pipe",
1944	* an unsigned int encoded as:
1945	*
1946	* - direction: bit 7 (0 = Host-to-Device [Out],
1947	* 1 = Device-to-Host [In] ...
1948	* like endpoint bEndpointAddress)
1949	* - device address: bits 8-14 ... bit positions known to uhci-hcd
1950	* - endpoint: bits 15-18 ... bit positions known to uhci-hcd
1951	* - pipe type: bits 30-31 (00 = isochronous, 01 = interrupt,
1952	* 10 = control, 11 = bulk)
1953	*
1954	* Given the device address and endpoint descriptor, pipes are redundant.
1955	*/
1956
1957	/* NOTE: these are not the standard USB_ENDPOINT_XFER_* values!! */
1958	/* (yet ... they're the values used by usbfs) */
1959	#define PIPE_ISOCHRONOUS 0
1960	#define PIPE_INTERRUPT 1
1961	#define PIPE_CONTROL 2
1962	#define PIPE_BULK 3
1963
1964	#define usb_pipein(pipe) ((pipe) & USB_DIR_IN)
1965	#define usb_pipeout(pipe) (!usb_pipein(pipe))
1966
1967	#define usb_pipedevice(pipe) (((pipe) >> 8) & 0x7f)
1968	#define usb_pipeendpoint(pipe) (((pipe) >> 15) & 0xf)
1969
1970	#define usb_pipetype(pipe) (((pipe) >> 30) & 3)
1971	#define usb_pipeisoc(pipe) (usb_pipetype((pipe)) == PIPE_ISOCHRONOUS)
1972	#define usb_pipeint(pipe) (usb_pipetype((pipe)) == PIPE_INTERRUPT)
1973	#define usb_pipecontrol(pipe) (usb_pipetype((pipe)) == PIPE_CONTROL)
1974	#define usb_pipebulk(pipe) (usb_pipetype((pipe)) == PIPE_BULK)
1975
1976	static inline unsigned int __create_pipe(struct usb_device *dev,
1977	unsigned int endpoint)
1978	{
1979	return (dev->devnum << 8) | (endpoint << 15);
1980	}
1981
1982	/* Create various pipes... */
1983	#define usb_sndctrlpipe(dev, endpoint) \
1984	((PIPE_CONTROL << 30) | __create_pipe(dev, endpoint))
1985	#define usb_rcvctrlpipe(dev, endpoint) \
1986	((PIPE_CONTROL << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
1987	#define usb_sndisocpipe(dev, endpoint) \
1988	((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev, endpoint))
1989	#define usb_rcvisocpipe(dev, endpoint) \
1990	((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
1991	#define usb_sndbulkpipe(dev, endpoint) \
1992	((PIPE_BULK << 30) | __create_pipe(dev, endpoint))
1993	#define usb_rcvbulkpipe(dev, endpoint) \
1994	((PIPE_BULK << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
1995	#define usb_sndintpipe(dev, endpoint) \
1996	((PIPE_INTERRUPT << 30) | __create_pipe(dev, endpoint))
1997	#define usb_rcvintpipe(dev, endpoint) \
1998	((PIPE_INTERRUPT << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
1999
2000	static inline struct usb_host_endpoint *
2001	usb_pipe_endpoint(struct usb_device *dev, unsigned int pipe)
2002	{
2003	struct usb_host_endpoint **eps;
2004	eps = usb_pipein(pipe) ? dev->ep_in : dev->ep_out;
2005	return eps[usb_pipeendpoint(pipe)];
2006	}
2007
2008	static inline u16 usb_maxpacket(struct usb_device *udev, int pipe)
2009	{
2010	struct usb_host_endpoint *ep = usb_pipe_endpoint(dev: udev, pipe);
2011
2012	if (!ep)
2013	return 0;
2014
2015	/* NOTE: only 0x07ff bits are for packet size... */
2016	return usb_endpoint_maxp(epd: &ep->desc);
2017	}
2018
2019	/* translate USB error codes to codes user space understands */
2020	static inline int usb_translate_errors(int error_code)
2021	{
2022	switch (error_code) {
2023	case 0:
2024	case -ENOMEM:
2025	case -ENODEV:
2026	case -EOPNOTSUPP:
2027	return error_code;
2028	default:
2029	return -EIO;
2030	}
2031	}
2032
2033	/* Events from the usb core */
2034	#define USB_DEVICE_ADD 0x0001
2035	#define USB_DEVICE_REMOVE 0x0002
2036	#define USB_BUS_ADD 0x0003
2037	#define USB_BUS_REMOVE 0x0004
2038	extern void usb_register_notify(struct notifier_block *nb);
2039	extern void usb_unregister_notify(struct notifier_block *nb);
2040
2041	/* debugfs stuff */
2042	extern struct dentry *usb_debug_root;
2043
2044	/* LED triggers */
2045	enum usb_led_event {
2046	USB_LED_EVENT_HOST = 0,
2047	USB_LED_EVENT_GADGET = 1,
2048	};
2049
2050	#ifdef CONFIG_USB_LED_TRIG
2051	extern void usb_led_activity(enum usb_led_event ev);
2052	#else
2053	static inline void usb_led_activity(enum usb_led_event ev) {}
2054	#endif
2055
2056	#endif /* __KERNEL__ */
2057
2058	#endif
2059