usb.h source code [Linux/include/linux/usb.h]

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

Browse the source code of Linux/include/linux/usb.h