usb.h 76.1 KB
Newer Older
1
/* SPDX-License-Identifier: GPL-2.0 */
Linus Torvalds's avatar
Linus Torvalds committed
2
3
4
5
#ifndef __LINUX_USB_H
#define __LINUX_USB_H

#include <linux/mod_devicetable.h>
6
#include <linux/usb/ch9.h>
Linus Torvalds's avatar
Linus Torvalds committed
7
8

#define USB_MAJOR			180
9
#define USB_DEVICE_MAJOR		189
Linus Torvalds's avatar
Linus Torvalds committed
10
11
12
13
14
15
16
17
18
19
20
21
22


#ifdef __KERNEL__

#include <linux/errno.h>        /* for -ENODEV */
#include <linux/delay.h>	/* for mdelay() */
#include <linux/interrupt.h>	/* for in_interrupt() */
#include <linux/list.h>		/* for struct list_head */
#include <linux/kref.h>		/* for struct kref */
#include <linux/device.h>	/* for struct device */
#include <linux/fs.h>		/* for struct file_operations */
#include <linux/completion.h>	/* for struct completion */
#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 */
Linus Torvalds's avatar
Linus Torvalds committed
25
26
27

struct usb_device;
struct usb_driver;
28
struct wusb_dev;
Linus Torvalds's avatar
Linus Torvalds committed
29
30
31
32
33
34
35
36
37
38
39
40

/*-------------------------------------------------------------------------*/

/*
 * Host-side wrappers for standard USB descriptors ... these are parsed
 * from the data provided by devices.  Parsing turns them from a flat
 * sequence of descriptors into a hierarchy:
 *
 *  - devices have one (usually) or more configs;
 *  - configs have one (often) or more interfaces;
 *  - interfaces have one (usually) or more settings;
 *  - each interface setting has zero or (usually) more endpoints.
41
 *  - a SuperSpeed endpoint has a companion descriptor
Linus Torvalds's avatar
Linus Torvalds committed
42
43
44
45
46
47
 *
 * And there might be other descriptors mixed in with those.
 *
 * Devices may also have class-specific or vendor-specific descriptors.
 */

48
49
struct ep_device;

Linus Torvalds's avatar
Linus Torvalds committed
50
51
52
/**
 * struct usb_host_endpoint - host-side endpoint descriptor and queue
 * @desc: descriptor for this endpoint, wMaxPacketSize in native byteorder
53
 * @ss_ep_comp: SuperSpeed companion descriptor for this endpoint
54
 * @ssp_isoc_ep_comp: SuperSpeedPlus isoc companion descriptor for this endpoint
Linus Torvalds's avatar
Linus Torvalds committed
55
56
57
 * @urb_list: urbs queued to this endpoint; maintained by usbcore
 * @hcpriv: for use by HCD; typically holds hardware dma queue head (QH)
 *	with one or more transfer descriptors (TDs) per urb
Randy Dunlap's avatar
Randy Dunlap committed
58
 * @ep_dev: ep_device for sysfs info
Linus Torvalds's avatar
Linus Torvalds committed
59
60
 * @extra: descriptors following this endpoint in the configuration
 * @extralen: how many bytes of "extra" are valid
Alan Stern's avatar
Alan Stern committed
61
 * @enabled: URBs may be submitted to this endpoint
62
 * @streams: number of USB-3 streams allocated on the endpoint
Linus Torvalds's avatar
Linus Torvalds committed
63
64
65
66
67
 *
 * USB requests are always queued to a given endpoint, identified by a
 * descriptor within an active interface in a given USB configuration.
 */
struct usb_host_endpoint {
68
69
	struct usb_endpoint_descriptor		desc;
	struct usb_ss_ep_comp_descriptor	ss_ep_comp;
70
	struct usb_ssp_isoc_ep_comp_descriptor	ssp_isoc_ep_comp;
Linus Torvalds's avatar
Linus Torvalds committed
71
72
	struct list_head		urb_list;
	void				*hcpriv;
73
	struct ep_device		*ep_dev;	/* For sysfs info */
Linus Torvalds's avatar
Linus Torvalds committed
74
75
76

	unsigned char *extra;   /* Extra descriptors */
	int extralen;
Alan Stern's avatar
Alan Stern committed
77
	int enabled;
78
	int streams;
Linus Torvalds's avatar
Linus Torvalds committed
79
80
81
82
83
84
};

/* host-side wrapper for one interface setting's parsed descriptors */
struct usb_host_interface {
	struct usb_interface_descriptor	desc;

85
86
87
	int extralen;
	unsigned char *extra;   /* Extra descriptors */

88
	/* array of desc.bNumEndpoints endpoints associated with this
Linus Torvalds's avatar
Linus Torvalds committed
89
90
91
92
93
94
95
96
97
98
99
100
101
102
	 * interface setting.  these will be in no particular order.
	 */
	struct usb_host_endpoint *endpoint;

	char *string;		/* iInterface string, if present */
};

enum usb_interface_condition {
	USB_INTERFACE_UNBOUND = 0,
	USB_INTERFACE_BINDING,
	USB_INTERFACE_BOUND,
	USB_INTERFACE_UNBINDING,
};

103
104
105
106
107
108
109
int __must_check
usb_find_common_endpoints(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **bulk_in,
		struct usb_endpoint_descriptor **bulk_out,
		struct usb_endpoint_descriptor **int_in,
		struct usb_endpoint_descriptor **int_out);

110
111
112
113
114
115
116
int __must_check
usb_find_common_endpoints_reverse(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **bulk_in,
		struct usb_endpoint_descriptor **bulk_out,
		struct usb_endpoint_descriptor **int_in,
		struct usb_endpoint_descriptor **int_out);

117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
static inline int __must_check
usb_find_bulk_in_endpoint(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **bulk_in)
{
	return usb_find_common_endpoints(alt, bulk_in, NULL, NULL, NULL);
}

static inline int __must_check
usb_find_bulk_out_endpoint(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **bulk_out)
{
	return usb_find_common_endpoints(alt, NULL, bulk_out, NULL, NULL);
}

static inline int __must_check
usb_find_int_in_endpoint(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **int_in)
{
	return usb_find_common_endpoints(alt, NULL, NULL, int_in, NULL);
}

static inline int __must_check
usb_find_int_out_endpoint(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **int_out)
{
	return usb_find_common_endpoints(alt, NULL, NULL, NULL, int_out);
}

145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
static inline int __must_check
usb_find_last_bulk_in_endpoint(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **bulk_in)
{
	return usb_find_common_endpoints_reverse(alt, bulk_in, NULL, NULL, NULL);
}

static inline int __must_check
usb_find_last_bulk_out_endpoint(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **bulk_out)
{
	return usb_find_common_endpoints_reverse(alt, NULL, bulk_out, NULL, NULL);
}

static inline int __must_check
usb_find_last_int_in_endpoint(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **int_in)
{
	return usb_find_common_endpoints_reverse(alt, NULL, NULL, int_in, NULL);
}

static inline int __must_check
usb_find_last_int_out_endpoint(struct usb_host_interface *alt,
		struct usb_endpoint_descriptor **int_out)
{
	return usb_find_common_endpoints_reverse(alt, NULL, NULL, NULL, int_out);
}

Linus Torvalds's avatar
Linus Torvalds committed
173
174
175
/**
 * struct usb_interface - what usb device drivers talk to
 * @altsetting: array of interface structures, one for each alternate
176
177
 *	setting that may be selected.  Each one includes a set of
 *	endpoint configurations.  They will be in no particular order.
Linus Torvalds's avatar
Linus Torvalds committed
178
 * @cur_altsetting: the current altsetting.
179
 * @num_altsetting: number of altsettings defined.
Randy Dunlap's avatar
Randy Dunlap committed
180
 * @intf_assoc: interface association descriptor
Linus Torvalds's avatar
Linus Torvalds committed
181
182
183
184
185
186
187
188
 * @minor: the minor number assigned to this interface, if this
 *	interface is bound to a driver that uses the USB major number.
 *	If this interface does not use the USB major, this field should
 *	be unused.  The driver should set this value in the probe()
 *	function of the driver, after it has been assigned a minor
 *	number from the USB core by calling usb_register_dev().
 * @condition: binding state of the interface: not bound, binding
 *	(in probe()), bound to a driver, or unbinding (in disconnect())
Randy Dunlap's avatar
Randy Dunlap committed
189
 * @sysfs_files_created: sysfs attributes exist
Alan Stern's avatar
Alan Stern committed
190
 * @ep_devs_created: endpoint child pseudo-devices exist
191
 * @unregistering: flag set when the interface is being unregistered
192
193
 * @needs_remote_wakeup: flag set when the driver requires remote-wakeup
 *	capability during autosuspend.
194
195
 * @needs_altsetting0: flag set when a set-interface request for altsetting 0
 *	has been deferred.
196
197
 * @needs_binding: flag set when the driver should be re-probed or unbound
 *	following a reset or suspend operation it doesn't support.
198
199
 * @authorized: This allows to (de)authorize individual interfaces instead
 *	a whole device in contrast to the device authorization.
Linus Torvalds's avatar
Linus Torvalds committed
200
 * @dev: driver model's view of this device
201
202
 * @usb_dev: if an interface is bound to the USB major, this will point
 *	to the sysfs representation for that device.
203
 * @reset_ws: Used for scheduling resets from atomic context.
204
205
 * @resetting_device: USB core reset the device, so use alt setting 0 as
 *	current; needs bandwidth alloc after reset.
Linus Torvalds's avatar
Linus Torvalds committed
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 *
 * USB device drivers attach to interfaces on a physical device.  Each
 * interface encapsulates a single high level function, such as feeding
 * an audio stream to a speaker or reporting a change in a volume control.
 * Many USB devices only have one interface.  The protocol used to talk to
 * an interface's endpoints can be defined in a usb "class" specification,
 * or by a product's vendor.  The (default) control endpoint is part of
 * every interface, but is never listed among the interface's descriptors.
 *
 * The driver that is bound to the interface can use standard driver model
 * calls such as dev_get_drvdata() on the dev member of this structure.
 *
 * Each interface may have alternate settings.  The initial configuration
 * of a device sets altsetting 0, but the device driver can change
 * that setting using usb_set_interface().  Alternate settings are often
221
 * used to control the use of periodic endpoints, such as by having
Linus Torvalds's avatar
Linus Torvalds committed
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 * different endpoints use different amounts of reserved USB bandwidth.
 * All standards-conformant USB devices that use isochronous endpoints
 * will use them in non-default settings.
 *
 * The USB specification says that alternate setting numbers must run from
 * 0 to one less than the total number of alternate settings.  But some
 * devices manage to mess this up, and the structures aren't necessarily
 * stored in numerical order anyhow.  Use usb_altnum_to_altsetting() to
 * look up an alternate setting in the altsetting array based on its number.
 */
struct usb_interface {
	/* array of alternate settings for this interface,
	 * stored in no particular order */
	struct usb_host_interface *altsetting;

	struct usb_host_interface *cur_altsetting;	/* the currently
					 * active alternate setting */
	unsigned num_altsetting;	/* number of alternate settings */

241
242
243
244
	/* If there is an interface association descriptor then it will list
	 * the associated interfaces */
	struct usb_interface_assoc_descriptor *intf_assoc;

245
246
	int minor;			/* minor number this interface is
					 * bound to */
Linus Torvalds's avatar
Linus Torvalds committed
247
	enum usb_interface_condition condition;		/* state of binding */
248
	unsigned sysfs_files_created:1;	/* the sysfs attributes exist */
Alan Stern's avatar
Alan Stern committed
249
	unsigned ep_devs_created:1;	/* endpoint "devices" exist */
250
	unsigned unregistering:1;	/* unregistration is in progress */
251
	unsigned needs_remote_wakeup:1;	/* driver requires remote wakeup */
252
	unsigned needs_altsetting0:1;	/* switch to altsetting 0 is pending */
253
	unsigned needs_binding:1;	/* needs delayed unbind/rebind */
254
	unsigned resetting_device:1;	/* true: bandwidth alloc after reset */
255
	unsigned authorized:1;		/* used for interface authorization */
256

Linus Torvalds's avatar
Linus Torvalds committed
257
	struct device dev;		/* interface specific device info */
258
	struct device *usb_dev;
259
	struct work_struct reset_ws;	/* for resets in atomic context */
Linus Torvalds's avatar
Linus Torvalds committed
260
261
262
};
#define	to_usb_interface(d) container_of(d, struct usb_interface, dev)

263
static inline void *usb_get_intfdata(struct usb_interface *intf)
Linus Torvalds's avatar
Linus Torvalds committed
264
{
265
	return dev_get_drvdata(&intf->dev);
Linus Torvalds's avatar
Linus Torvalds committed
266
267
}

268
static inline void usb_set_intfdata(struct usb_interface *intf, void *data)
Linus Torvalds's avatar
Linus Torvalds committed
269
270
271
272
273
274
275
{
	dev_set_drvdata(&intf->dev, data);
}

struct usb_interface *usb_get_intf(struct usb_interface *intf);
void usb_put_intf(struct usb_interface *intf);

276
277
/* Hard limit */
#define USB_MAXENDPOINTS	30
Linus Torvalds's avatar
Linus Torvalds committed
278
279
/* this maximum is arbitrary */
#define USB_MAXINTERFACES	32
280
#define USB_MAXIADS		(USB_MAXINTERFACES/2)
Linus Torvalds's avatar
Linus Torvalds committed
281

282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
/*
 * USB Resume Timer: Every Host controller driver should drive the resume
 * signalling on the bus for the amount of time defined by this macro.
 *
 * That way we will have a 'stable' behavior among all HCDs supported by Linux.
 *
 * Note that the USB Specification states we should drive resume for *at least*
 * 20 ms, but it doesn't give an upper bound. This creates two possible
 * situations which we want to avoid:
 *
 * (a) sometimes an msleep(20) might expire slightly before 20 ms, which causes
 * us to fail USB Electrical Tests, thus failing Certification
 *
 * (b) Some (many) devices actually need more than 20 ms of resume signalling,
 * and while we can argue that's against the USB Specification, we don't have
 * control over which devices a certification laboratory will be using for
 * certification. If CertLab uses a device which was tested against Windows and
 * that happens to have relaxed resume signalling rules, we might fall into
 * situations where we fail interoperability and electrical tests.
 *
 * In order to avoid both conditions, we're using a 40 ms resume timeout, which
 * should cope with both LPJ calibration errors and devices not following every
 * detail of the USB Specification.
 */
#define USB_RESUME_TIMEOUT	40 /* ms */

Linus Torvalds's avatar
Linus Torvalds committed
308
309
310
311
312
313
314
315
316
317
318
319
/**
 * struct usb_interface_cache - long-term representation of a device interface
 * @num_altsetting: number of altsettings defined.
 * @ref: reference counter.
 * @altsetting: variable-length array of interface structures, one for
 *	each alternate setting that may be selected.  Each one includes a
 *	set of endpoint configurations.  They will be in no particular order.
 *
 * These structures persist for the lifetime of a usb_device, unlike
 * struct usb_interface (which persists only as long as its configuration
 * is installed).  The altsetting arrays can be accessed through these
 * structures at any time, permitting comparison of configurations and
320
 * providing support for the /sys/kernel/debug/usb/devices pseudo-file.
Linus Torvalds's avatar
Linus Torvalds committed
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
 */
struct usb_interface_cache {
	unsigned num_altsetting;	/* number of alternate settings */
	struct kref ref;		/* reference counter */

	/* variable-length array of alternate settings for this interface,
	 * stored in no particular order */
	struct usb_host_interface altsetting[0];
};
#define	ref_to_usb_interface_cache(r) \
		container_of(r, struct usb_interface_cache, ref)
#define	altsetting_to_usb_interface_cache(a) \
		container_of(a, struct usb_interface_cache, altsetting[0])

/**
 * struct usb_host_config - representation of a device's configuration
 * @desc: the device's configuration descriptor.
 * @string: pointer to the cached version of the iConfiguration string, if
 *	present for this configuration.
Randy Dunlap's avatar
Randy Dunlap committed
340
 * @intf_assoc: list of any interface association descriptors in this config
Linus Torvalds's avatar
Linus Torvalds committed
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
 * @interface: array of pointers to usb_interface structures, one for each
 *	interface in the configuration.  The number of interfaces is stored
 *	in desc.bNumInterfaces.  These pointers are valid only while the
 *	the configuration is active.
 * @intf_cache: array of pointers to usb_interface_cache structures, one
 *	for each interface in the configuration.  These structures exist
 *	for the entire life of the device.
 * @extra: pointer to buffer containing all extra descriptors associated
 *	with this configuration (those preceding the first interface
 *	descriptor).
 * @extralen: length of the extra descriptors buffer.
 *
 * USB devices may have multiple configurations, but only one can be active
 * at any time.  Each encapsulates a different operational environment;
 * for example, a dual-speed device would have separate configurations for
 * full-speed and high-speed operation.  The number of configurations
 * available is stored in the device descriptor as bNumConfigurations.
 *
 * A configuration can contain multiple interfaces.  Each corresponds to
 * a different function of the USB device, and all are available whenever
 * the configuration is active.  The USB standard says that interfaces
 * are supposed to be numbered from 0 to desc.bNumInterfaces-1, but a lot
 * of devices get this wrong.  In addition, the interface array is not
 * guaranteed to be sorted in numerical order.  Use usb_ifnum_to_if() to
 * look up an interface entry based on its number.
 *
 * Device drivers should not attempt to activate configurations.  The choice
 * of which configuration to install is a policy decision based on such
 * considerations as available power, functionality provided, and the user's
370
 * desires (expressed through userspace tools).  However, drivers can call
Linus Torvalds's avatar
Linus Torvalds committed
371
372
373
374
375
376
 * usb_reset_configuration() to reinitialize the current configuration and
 * all its interfaces.
 */
struct usb_host_config {
	struct usb_config_descriptor	desc;

377
	char *string;		/* iConfiguration string, if present */
378
379
380
381
382

	/* List of any Interface Association Descriptors in this
	 * configuration. */
	struct usb_interface_assoc_descriptor *intf_assoc[USB_MAXIADS];

Linus Torvalds's avatar
Linus Torvalds committed
383
384
385
386
387
388
389
390
391
392
393
394
	/* the interfaces associated with this configuration,
	 * stored in no particular order */
	struct usb_interface *interface[USB_MAXINTERFACES];

	/* Interface information available even when this is not the
	 * active configuration */
	struct usb_interface_cache *intf_cache[USB_MAXINTERFACES];

	unsigned char *extra;   /* Extra descriptors */
	int extralen;
};

Andiry Xu's avatar
Andiry Xu committed
395
396
397
398
399
400
401
/* USB2.0 and USB3.0 device BOS descriptor set */
struct usb_host_bos {
	struct usb_bos_descriptor	*desc;

	/* wireless cap descriptor is handled by wusb */
	struct usb_ext_cap_descriptor	*ext_cap;
	struct usb_ss_cap_descriptor	*ss_cap;
402
	struct usb_ssp_cap_descriptor	*ssp_cap;
Andiry Xu's avatar
Andiry Xu committed
403
	struct usb_ss_container_id_descriptor	*ss_id;
404
	struct usb_ptm_cap_descriptor	*ptm_cap;
Andiry Xu's avatar
Andiry Xu committed
405
406
};

Linus Torvalds's avatar
Linus Torvalds committed
407
int __usb_get_extra_descriptor(char *buffer, unsigned size,
408
	unsigned char type, void **ptr, size_t min);
409
410
411
#define usb_get_extra_descriptor(ifpoint, type, ptr) \
				__usb_get_extra_descriptor((ifpoint)->extra, \
				(ifpoint)->extralen, \
412
				type, (void **)ptr, sizeof(**(ptr)))
Linus Torvalds's avatar
Linus Torvalds committed
413

414
/* ----------------------------------------------------------------------- */
Linus Torvalds's avatar
Linus Torvalds committed
415
416
417
418
419
420
421
422
423
424
425

/* USB device number allocation bitmap */
struct usb_devmap {
	unsigned long devicemap[128 / (8*sizeof(unsigned long))];
};

/*
 * Allocated per bus (tree of devices) we have:
 */
struct usb_bus {
	struct device *controller;	/* host/master side hardware */
426
	struct device *sysdev;		/* as seen from firmware or bus */
Linus Torvalds's avatar
Linus Torvalds committed
427
	int busnum;			/* Bus number (in order of reg) */
428
	const char *bus_name;		/* stable id (PCI slot_name etc) */
429
	u8 uses_dma;			/* Does the host controller use DMA? */
430
431
432
433
	u8 uses_pio_for_control;	/*
					 * Does the host controller use PIO
					 * for control transfers?
					 */
Linus Torvalds's avatar
Linus Torvalds committed
434
435
436
	u8 otg_port;			/* 0, or number of OTG/HNP port */
	unsigned is_b_host:1;		/* true during some HNP roleswitches */
	unsigned b_hnp_enable:1;	/* OTG: did A-Host enable HNP? */
437
438
439
440
441
	unsigned no_stop_on_short:1;    /*
					 * Quirk: some controllers don't stop
					 * the ep queue on a short transfer
					 * with the URB_SHORT_NOT_OK flag set.
					 */
442
	unsigned no_sg_constraint:1;	/* no sg constraint */
443
	unsigned sg_tablesize;		/* 0 or largest number of sg list entries */
Linus Torvalds's avatar
Linus Torvalds committed
444

445
446
	int devnum_next;		/* Next open device number in
					 * round-robin allocation */
447
	struct mutex devnum_next_mutex; /* devnum_next mutex */
Linus Torvalds's avatar
Linus Torvalds committed
448
449
450

	struct usb_devmap devmap;	/* device address allocation map */
	struct usb_device *root_hub;	/* Root hub */
451
	struct usb_bus *hs_companion;	/* Companion EHCI bus, if any */
Linus Torvalds's avatar
Linus Torvalds committed
452
453
454
455
456
457
458
459
460
461
462

	int bandwidth_allocated;	/* on this bus: how much of the time
					 * reserved for periodic (intr/iso)
					 * requests is used, on average?
					 * Units: microseconds/frame.
					 * Limits: Full/low speed reserve 90%,
					 * while high speed reserves 80%.
					 */
	int bandwidth_int_reqs;		/* number of Interrupt requests */
	int bandwidth_isoc_reqs;	/* number of Isoc. requests */

463
464
	unsigned resuming_ports;	/* bit array: resuming root-hub ports */

465
#if defined(CONFIG_USB_MON) || defined(CONFIG_USB_MON_MODULE)
Linus Torvalds's avatar
Linus Torvalds committed
466
467
468
469
470
	struct mon_bus *mon_bus;	/* non-null when associated */
	int monitored;			/* non-zero when monitored */
#endif
};

471
struct usb_dev_state;
472

473
/* ----------------------------------------------------------------------- */
Linus Torvalds's avatar
Linus Torvalds committed
474
475
476

struct usb_tt;

477
478
479
480
481
482
enum usb_device_removable {
	USB_DEVICE_REMOVABLE_UNKNOWN = 0,
	USB_DEVICE_REMOVABLE,
	USB_DEVICE_FIXED,
};

483
484
485
486
487
488
489
enum usb_port_connect_type {
	USB_PORT_CONNECT_TYPE_UNKNOWN = 0,
	USB_PORT_CONNECT_TYPE_HOT_PLUG,
	USB_PORT_CONNECT_TYPE_HARD_WIRED,
	USB_PORT_NOT_USED,
};

490
491
492
493
494
495
496
/*
 * USB port quirks.
 */

/* For the given port, prefer the old (faster) enumeration scheme. */
#define USB_PORT_QUIRK_OLD_SCHEME	BIT(0)

497
498
499
/* Decrease TRSTRCY to 10ms during device enumeration. */
#define USB_PORT_QUIRK_FAST_ENUM	BIT(1)

500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
/*
 * USB 2.0 Link Power Management (LPM) parameters.
 */
struct usb2_lpm_parameters {
	/* Best effort service latency indicate how long the host will drive
	 * resume on an exit from L1.
	 */
	unsigned int besl;

	/* Timeout value in microseconds for the L1 inactivity (LPM) timer.
	 * When the timer counts to zero, the parent hub will initiate a LPM
	 * transition to L1.
	 */
	int timeout;
};

516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
/*
 * USB 3.0 Link Power Management (LPM) parameters.
 *
 * PEL and SEL are USB 3.0 Link PM latencies for device-initiated LPM exit.
 * MEL is the USB 3.0 Link PM latency for host-initiated LPM exit.
 * All three are stored in nanoseconds.
 */
struct usb3_lpm_parameters {
	/*
	 * Maximum exit latency (MEL) for the host to send a packet to the
	 * device (either a Ping for isoc endpoints, or a data packet for
	 * interrupt endpoints), the hubs to decode the packet, and for all hubs
	 * in the path to transition the links to U0.
	 */
	unsigned int mel;
	/*
	 * Maximum exit latency for a device-initiated LPM transition to bring
	 * all links into U0.  Abbreviated as "PEL" in section 9.4.12 of the USB
	 * 3.0 spec, with no explanation of what "P" stands for.  "Path"?
	 */
	unsigned int pel;

	/*
	 * The System Exit Latency (SEL) includes PEL, and three other
	 * latencies.  After a device initiates a U0 transition, it will take
	 * some time from when the device sends the ERDY to when it will finally
	 * receive the data packet.  Basically, SEL should be the worse-case
	 * latency from when a device starts initiating a U0 transition to when
	 * it will get data.
	 */
	unsigned int sel;
547
548
549
550
551
552
	/*
	 * The idle timeout value that is currently programmed into the parent
	 * hub for this device.  When the timer counts to zero, the parent hub
	 * will initiate an LPM transition to either U1 or U2.
	 */
	int timeout;
553
554
};

555
/**
Linus Torvalds's avatar
Linus Torvalds committed
556
 * struct usb_device - kernel's representation of a USB device
557
558
 * @devnum: device number; address on a USB bus
 * @devpath: device ID string for use in messages (e.g., /port/...)
559
 * @route: tree topology hex string for use with xHCI
560
561
 * @state: device state: configured, not attached, etc.
 * @speed: device speed: high/full/low (or error)
562
563
 * @rx_lanes: number of rx lanes in use, USB 3.2 adds dual-lane support
 * @tx_lanes: number of tx lanes in use, USB 3.2 adds dual-lane support
564
565
566
567
568
569
570
571
 * @tt: Transaction Translator info; used with low/full speed dev, highspeed hub
 * @ttport: device port on that tt hub
 * @toggle: one bit for each endpoint, with ([0] = IN, [1] = OUT) endpoints
 * @parent: our hub, unless we're the root
 * @bus: bus we're part of
 * @ep0: endpoint 0 data (default control pipe)
 * @dev: generic device interface
 * @descriptor: USB device descriptor
Andiry Xu's avatar
Andiry Xu committed
572
 * @bos: USB device BOS descriptor set
573
574
575
576
577
578
579
580
 * @config: all of the device's configs
 * @actconfig: the active configuration
 * @ep_in: array of IN endpoints
 * @ep_out: array of OUT endpoints
 * @rawdescriptors: raw descriptors for each config
 * @bus_mA: Current available from the bus
 * @portnum: parent port number (origin 1)
 * @level: number of USB hub ancestors
581
 * @devaddr: device address, XHCI: assigned by HW, others: same as devnum
582
583
584
585
586
587
588
589
 * @can_submit: URBs may be submitted
 * @persist_enabled:  USB_PERSIST enabled for this device
 * @have_langid: whether string_langid is valid
 * @authorized: policy has said we can use it;
 *	(user space) policy determines if we authorize this device to be
 *	used or not. By default, wired USB devices are authorized.
 *	WUSB devices are not, until we authorize them from user space.
 *	FIXME -- complete doc
590
 * @authenticated: Crypto authentication passed
591
 * @wusb: device is Wireless USB
592
 * @lpm_capable: device supports LPM
Andiry Xu's avatar
Andiry Xu committed
593
 * @usb2_hw_lpm_capable: device can perform USB2 hardware LPM
594
 * @usb2_hw_lpm_besl_capable: device can perform USB2 hardware BESL LPM
595
596
 * @usb2_hw_lpm_enabled: USB2 hardware LPM is enabled
 * @usb2_hw_lpm_allowed: Userspace allows USB 2.0 LPM to be enabled
597
598
 * @usb3_lpm_u1_enabled: USB3 hardware U1 LPM enabled
 * @usb3_lpm_u2_enabled: USB3 hardware U2 LPM enabled
599
600
601
602
603
604
605
606
607
608
609
610
 * @string_langid: language ID for strings
 * @product: iProduct string, if present (static)
 * @manufacturer: iManufacturer string, if present (static)
 * @serial: iSerialNumber string, if present (static)
 * @filelist: usbfs files that are open to this device
 * @maxchild: number of ports if hub
 * @quirks: quirks of the whole device
 * @urbnum: number of URBs submitted for the whole device
 * @active_duration: total time device is not suspended
 * @connect_time: time device was first connected
 * @do_remote_wakeup:  remote wakeup should be enabled
 * @reset_resume: needs reset instead of resume
Alan Stern's avatar
Alan Stern committed
611
 * @port_is_suspended: the upstream port is suspended (L2 or U3)
612
613
 * @wusb_dev: if this is a Wireless USB device, link to the WUSB
 *	specific data for the device.
614
 * @slot_id: Slot ID assigned by xHCI
615
 * @removable: Device can be physically removed from this port
616
 * @l1_params: best effor service latency for USB2 L1 LPM state, and L1 timeout.
617
618
619
620
621
622
 * @u1_params: exit latencies for USB3 U1 LPM state, and hub-initiated timeout.
 * @u2_params: exit latencies for USB3 U2 LPM state, and hub-initiated timeout.
 * @lpm_disable_count: Ref count used by usb_disable_lpm() and usb_enable_lpm()
 *	to keep track of the number of functions that require USB 3.0 Link Power
 *	Management to be disabled for this usb_device.  This count should only
 *	be manipulated by those functions, with the bandwidth_mutex is held.
623
624
625
626
 * @hub_delay: cached value consisting of:
 *		parent->hub_delay + wHubDelay + tTPTransmissionDelay (40ns)
 *
 *	Will be used as wValue for SetIsochDelay requests.
Linus Torvalds's avatar
Linus Torvalds committed
627
 *
628
 * Notes:
Linus Torvalds's avatar
Linus Torvalds committed
629
630
631
632
 * Usbcore drivers should not set usbdev->state directly.  Instead use
 * usb_set_device_state().
 */
struct usb_device {
633
	int		devnum;
634
	char		devpath[16];
635
	u32		route;
636
637
	enum usb_device_state	state;
	enum usb_device_speed	speed;
638
639
	unsigned int		rx_lanes;
	unsigned int		tx_lanes;
Linus Torvalds's avatar
Linus Torvalds committed
640

641
642
	struct usb_tt	*tt;
	int		ttport;
Linus Torvalds's avatar
Linus Torvalds committed
643

644
	unsigned int toggle[2];
Linus Torvalds's avatar
Linus Torvalds committed
645

646
647
	struct usb_device *parent;
	struct usb_bus *bus;
Linus Torvalds's avatar
Linus Torvalds committed
648
649
	struct usb_host_endpoint ep0;

650
	struct device dev;
Linus Torvalds's avatar
Linus Torvalds committed
651

652
	struct usb_device_descriptor descriptor;
Andiry Xu's avatar
Andiry Xu committed
653
	struct usb_host_bos *bos;
654
	struct usb_host_config *config;
Linus Torvalds's avatar
Linus Torvalds committed
655

656
	struct usb_host_config *actconfig;
Linus Torvalds's avatar
Linus Torvalds committed
657
658
659
	struct usb_host_endpoint *ep_in[16];
	struct usb_host_endpoint *ep_out[16];

660
	char **rawdescriptors;
Linus Torvalds's avatar
Linus Torvalds committed
661

662
663
664
	unsigned short bus_mA;
	u8 portnum;
	u8 level;
665
	u8 devaddr;
666

667
668
669
670
	unsigned can_submit:1;
	unsigned persist_enabled:1;
	unsigned have_langid:1;
	unsigned authorized:1;
671
	unsigned authenticated:1;
672
	unsigned wusb:1;
673
	unsigned lpm_capable:1;
Andiry Xu's avatar
Andiry Xu committed
674
	unsigned usb2_hw_lpm_capable:1;
675
	unsigned usb2_hw_lpm_besl_capable:1;
Andiry Xu's avatar
Andiry Xu committed
676
	unsigned usb2_hw_lpm_enabled:1;
677
	unsigned usb2_hw_lpm_allowed:1;
678
679
	unsigned usb3_lpm_u1_enabled:1;
	unsigned usb3_lpm_u2_enabled:1;
680
	int string_langid;
Linus Torvalds's avatar
Linus Torvalds committed
681

682
	/* static strings from the device */
683
684
685
	char *product;
	char *manufacturer;
	char *serial;
686

Linus Torvalds's avatar
Linus Torvalds committed
687
688
	struct list_head filelist;

689
	int maxchild;
690

691
692
	u32 quirks;
	atomic_t urbnum;
693

694
	unsigned long active_duration;
Sarah Sharp's avatar
Sarah Sharp committed
695

696
#ifdef CONFIG_PM
697
698
699
700
	unsigned long connect_time;

	unsigned do_remote_wakeup:1;
	unsigned reset_resume:1;
Alan Stern's avatar
Alan Stern committed
701
	unsigned port_is_suspended:1;
702
#endif
703
	struct wusb_dev *wusb_dev;
704
	int slot_id;
705
	enum usb_device_removable removable;
706
	struct usb2_lpm_parameters l1_params;
707
708
	struct usb3_lpm_parameters u1_params;
	struct usb3_lpm_parameters u2_params;
709
	unsigned lpm_disable_count;
710
711

	u16 hub_delay;
Linus Torvalds's avatar
Linus Torvalds committed
712
713
714
};
#define	to_usb_device(d) container_of(d, struct usb_device, dev)

715
716
717
718
719
static inline struct usb_device *interface_to_usbdev(struct usb_interface *intf)
{
	return to_usb_device(intf->dev.parent);
}

Linus Torvalds's avatar
Linus Torvalds committed
720
721
extern struct usb_device *usb_get_dev(struct usb_device *dev);
extern void usb_put_dev(struct usb_device *dev);
722
723
724
725
726
727
728
729
730
731
732
extern struct usb_device *usb_hub_find_child(struct usb_device *hdev,
	int port1);

/**
 * usb_hub_for_each_child - iterate over all child devices on the hub
 * @hdev:  USB device belonging to the usb hub
 * @port1: portnum associated with child device
 * @child: child device pointer
 */
#define usb_hub_for_each_child(hdev, port1, child) \
	for (port1 = 1,	child =	usb_hub_find_child(hdev, port1); \
733
734
735
			port1 <= hdev->maxchild; \
			child = usb_hub_find_child(hdev, ++port1)) \
		if (!child) continue; else
Linus Torvalds's avatar
Linus Torvalds committed
736

737
/* USB device locking */
738
739
740
741
#define usb_lock_device(udev)			device_lock(&(udev)->dev)
#define usb_unlock_device(udev)			device_unlock(&(udev)->dev)
#define usb_lock_device_interruptible(udev)	device_lock_interruptible(&(udev)->dev)
#define usb_trylock_device(udev)		device_trylock(&(udev)->dev)
Linus Torvalds's avatar
Linus Torvalds committed
742
extern int usb_lock_device_for_reset(struct usb_device *udev,
743
				     const struct usb_interface *iface);
Linus Torvalds's avatar
Linus Torvalds committed
744
745
746

/* USB port reset for device reinitialization */
extern int usb_reset_device(struct usb_device *dev);
747
extern void usb_queue_reset_device(struct usb_interface *dev);
Linus Torvalds's avatar
Linus Torvalds committed
748

749
750
751
752
753
754
755
756
757
758
#ifdef CONFIG_ACPI
extern int usb_acpi_set_power_state(struct usb_device *hdev, int index,
	bool enable);
extern bool usb_acpi_power_manageable(struct usb_device *hdev, int index);
#else
static inline int usb_acpi_set_power_state(struct usb_device *hdev, int index,
	bool enable) { return 0; }
static inline bool usb_acpi_power_manageable(struct usb_device *hdev, int index)
	{ return true; }
#endif
Linus Torvalds's avatar
Linus Torvalds committed
759

760
/* USB autosuspend and autoresume */
761
#ifdef CONFIG_PM
762
763
extern void usb_enable_autosuspend(struct usb_device *udev);
extern void usb_disable_autosuspend(struct usb_device *udev);
764

765
766
extern int usb_autopm_get_interface(struct usb_interface *intf);
extern void usb_autopm_put_interface(struct usb_interface *intf);
767
768
extern int usb_autopm_get_interface_async(struct usb_interface *intf);
extern void usb_autopm_put_interface_async(struct usb_interface *intf);
769
770
extern void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
extern void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
771

772
773
static inline void usb_mark_last_busy(struct usb_device *udev)
{
774
	pm_runtime_mark_last_busy(&udev->dev);
775
776
}

777
778
#else

779
780
781
782
783
static inline int usb_enable_autosuspend(struct usb_device *udev)
{ return 0; }
static inline int usb_disable_autosuspend(struct usb_device *udev)
{ return 0; }

784
785
static inline int usb_autopm_get_interface(struct usb_interface *intf)
{ return 0; }
786
787
788
static inline int usb_autopm_get_interface_async(struct usb_interface *intf)
{ return 0; }

789
790
static inline void usb_autopm_put_interface(struct usb_interface *intf)
{ }
791
792
static inline void usb_autopm_put_interface_async(struct usb_interface *intf)
{ }
793
794
static inline void usb_autopm_get_interface_no_resume(
		struct usb_interface *intf)
795
{ }
796
797
static inline void usb_autopm_put_interface_no_suspend(
		struct usb_interface *intf)
798
{ }
799
800
static inline void usb_mark_last_busy(struct usb_device *udev)
{ }
801
#endif
802

803
804
805
806
807
808
extern int usb_disable_lpm(struct usb_device *udev);
extern void usb_enable_lpm(struct usb_device *udev);
/* Same as above, but these functions lock/unlock the bandwidth_mutex. */
extern int usb_unlocked_disable_lpm(struct usb_device *udev);
extern void usb_unlocked_enable_lpm(struct usb_device *udev);

809
810
811
extern int usb_disable_ltm(struct usb_device *udev);
extern void usb_enable_ltm(struct usb_device *udev);

812
813
static inline bool usb_device_supports_ltm(struct usb_device *udev)
{
Oliver Neukum's avatar
Oliver Neukum committed
814
	if (udev->speed < USB_SPEED_SUPER || !udev->bos || !udev->bos->ss_cap)
815
816
817
818
		return false;
	return udev->bos->ss_cap->bmAttributes & USB_LTM_SUPPORT;
}

819
820
821
822
823
static inline bool usb_device_no_sg_constraint(struct usb_device *udev)
{
	return udev && udev->bus && udev->bus->no_sg_constraint;
}

824

Linus Torvalds's avatar
Linus Torvalds committed
825
826
827
/*-------------------------------------------------------------------------*/

/* for drivers using iso endpoints */
828
extern int usb_get_current_frame_number(struct usb_device *usb_dev);
Linus Torvalds's avatar
Linus Torvalds committed
829

830
831
832
833
834
835
/* Sets up a group of bulk endpoints to support multiple stream IDs. */
extern int usb_alloc_streams(struct usb_interface *interface,
		struct usb_host_endpoint **eps, unsigned int num_eps,
		unsigned int num_streams, gfp_t mem_flags);

/* Reverts a group of bulk endpoints back to not using stream IDs. */
836
extern int usb_free_streams(struct usb_interface *interface,
837
838
839
		struct usb_host_endpoint **eps, unsigned int num_eps,
		gfp_t mem_flags);

Linus Torvalds's avatar
Linus Torvalds committed
840
841
/* used these for multi-interface device registration */
extern int usb_driver_claim_interface(struct usb_driver *driver,
842
			struct usb_interface *iface, void *priv);
Linus Torvalds's avatar
Linus Torvalds committed
843
844
845
846
847

/**
 * usb_interface_claimed - returns true iff an interface is claimed
 * @iface: the interface being checked
 *
848
849
850
851
 * Return: %true (nonzero) iff the interface is claimed, else %false
 * (zero).
 *
 * Note:
Linus Torvalds's avatar
Linus Torvalds committed
852
853
854
855
856
 * Callers must own the driver model's usb bus readlock.  So driver
 * probe() entries don't need extra locking, but other call contexts
 * may need to explicitly claim that lock.
 *
 */
857
858
static inline int usb_interface_claimed(struct usb_interface *iface)
{
Linus Torvalds's avatar
Linus Torvalds committed
859
860
861
862
863
864
865
	return (iface->dev.driver != NULL);
}

extern void usb_driver_release_interface(struct usb_driver *driver,
			struct usb_interface *iface);
const struct usb_device_id *usb_match_id(struct usb_interface *interface,
					 const struct usb_device_id *id);
866
867
extern int usb_match_one_id(struct usb_interface *interface,
			    const struct usb_device_id *id);
Linus Torvalds's avatar
Linus Torvalds committed
868

869
extern int usb_for_each_dev(void *data, int (*fn)(struct usb_device *, void *));
Linus Torvalds's avatar
Linus Torvalds committed
870
871
extern struct usb_interface *usb_find_interface(struct usb_driver *drv,
		int minor);
872
extern struct usb_interface *usb_ifnum_to_if(const struct usb_device *dev,
Linus Torvalds's avatar
Linus Torvalds committed
873
874
		unsigned ifnum);
extern struct usb_host_interface *usb_altnum_to_altsetting(
875
		const struct usb_interface *intf, unsigned int altnum);
876
877
878
879
extern struct usb_host_interface *usb_find_alt_setting(
		struct usb_host_config *config,
		unsigned int iface_num,
		unsigned int alt_num);
Linus Torvalds's avatar
Linus Torvalds committed
880

881
882
/* port claiming functions */
int usb_hub_claim_port(struct usb_device *hdev, unsigned port1,
883
		struct usb_dev_state *owner);
884
int usb_hub_release_port(struct usb_device *hdev, unsigned port1,
885
		struct usb_dev_state *owner);
Linus Torvalds's avatar
Linus Torvalds committed
886
887
888
889
890
891
892

/**
 * usb_make_path - returns stable device path in the usb tree
 * @dev: the device whose path is being constructed
 * @buf: where to put the string
 * @size: how big is "buf"?
 *
893
 * Return: Length of the string (> 0) or negative if size was too small.
Linus Torvalds's avatar
Linus Torvalds committed
894
 *
895
 * Note:
Linus Torvalds's avatar
Linus Torvalds committed
896
897
898
899
900
 * This identifier is intended to be "stable", reflecting physical paths in
 * hardware such as physical bus addresses for host controllers or ports on
 * USB hubs.  That makes it stay the same until systems are physically
 * reconfigured, by re-cabling a tree of USB devices or by moving USB host
 * controllers.  Adding and removing devices, including virtual root hubs
Lucas De Marchi's avatar
Lucas De Marchi committed
901
 * in host controller driver modules, does not change these path identifiers;
Linus Torvalds's avatar
Linus Torvalds committed
902
903
904
905
906
907
908
909
910
911
 * neither does rebooting or re-enumerating.  These are more useful identifiers
 * than changeable ("unstable") ones like bus numbers or device addresses.
 *
 * With a partial exception for devices connected to USB 2.0 root hubs, these
 * identifiers are also predictable.  So long as the device tree isn't changed,
 * plugging any USB device into a given hub port always gives it the same path.
 * Because of the use of "companion" controllers, devices connected to ports on
 * USB 2.0 root hubs (EHCI host controllers) will get one path ID if they are
 * high speed, and a different one if they are full or low speed.
 */
912
static inline int usb_make_path(struct usb_device *dev, char *buf, size_t size)
Linus Torvalds's avatar
Linus Torvalds committed
913
914
{
	int actual;
915
916
	actual = snprintf(buf, size, "usb-%s-%s", dev->bus->bus_name,
			  dev->devpath);
Linus Torvalds's avatar
Linus Torvalds committed
917
918
919
920
921
	return (actual >= (int)size) ? -1 : actual;
}

/*-------------------------------------------------------------------------*/

922
923
924
925
926
927
#define USB_DEVICE_ID_MATCH_DEVICE \
		(USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
#define USB_DEVICE_ID_MATCH_DEV_RANGE \
		(USB_DEVICE_ID_MATCH_DEV_LO | USB_DEVICE_ID_MATCH_DEV_HI)
#define USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION \
		(USB_DEVICE_ID_MATCH_DEVICE | USB_DEVICE_ID_MATCH_DEV_RANGE)
Linus Torvalds's avatar
Linus Torvalds committed
928
#define USB_DEVICE_ID_MATCH_DEV_INFO \
929
930
931
		(USB_DEVICE_ID_MATCH_DEV_CLASS | \
		USB_DEVICE_ID_MATCH_DEV_SUBCLASS | \
		USB_DEVICE_ID_MATCH_DEV_PROTOCOL)
Linus Torvalds's avatar
Linus Torvalds committed
932
#define USB_DEVICE_ID_MATCH_INT_INFO \
933
934
935
		(USB_DEVICE_ID_MATCH_INT_CLASS | \
		USB_DEVICE_ID_MATCH_INT_SUBCLASS | \
		USB_DEVICE_ID_MATCH_INT_PROTOCOL)
Linus Torvalds's avatar
Linus Torvalds committed
936
937
938
939
940
941
942
943
944

/**
 * USB_DEVICE - macro used to describe a specific usb device
 * @vend: the 16 bit USB Vendor ID
 * @prod: the 16 bit USB Product ID
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific device.
 */
945
#define USB_DEVICE(vend, prod) \
946
947
948
	.match_flags = USB_DEVICE_ID_MATCH_DEVICE, \
	.idVendor = (vend), \
	.idProduct = (prod)
Linus Torvalds's avatar
Linus Torvalds committed
949
/**
Randy Dunlap's avatar
Randy Dunlap committed
950
 * USB_DEVICE_VER - describe a specific usb device with a version range
Linus Torvalds's avatar
Linus Torvalds committed
951
952
953
954
955
956
957
958
 * @vend: the 16 bit USB Vendor ID
 * @prod: the 16 bit USB Product ID
 * @lo: the bcdDevice_lo value
 * @hi: the bcdDevice_hi value
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific device, with a version range.
 */
959
#define USB_DEVICE_VER(vend, prod, lo, hi) \
960
	.match_flags = USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION, \
961
962
963
964
	.idVendor = (vend), \
	.idProduct = (prod), \
	.bcdDevice_lo = (lo), \
	.bcdDevice_hi = (hi)
Linus Torvalds's avatar
Linus Torvalds committed
965

966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
/**
 * USB_DEVICE_INTERFACE_CLASS - describe a usb device with a specific interface class
 * @vend: the 16 bit USB Vendor ID
 * @prod: the 16 bit USB Product ID
 * @cl: bInterfaceClass value
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific interface class of devices.
 */
#define USB_DEVICE_INTERFACE_CLASS(vend, prod, cl) \
	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
		       USB_DEVICE_ID_MATCH_INT_CLASS, \
	.idVendor = (vend), \
	.idProduct = (prod), \
	.bInterfaceClass = (cl)

982
/**
Randy Dunlap's avatar
Randy Dunlap committed
983
 * USB_DEVICE_INTERFACE_PROTOCOL - describe a usb device with a specific interface protocol
984
985
986
987
988
989
990
 * @vend: the 16 bit USB Vendor ID
 * @prod: the 16 bit USB Product ID
 * @pr: bInterfaceProtocol value
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific interface protocol of devices.
 */
991
992
993
#define USB_DEVICE_INTERFACE_PROTOCOL(vend, prod, pr) \
	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
		       USB_DEVICE_ID_MATCH_INT_PROTOCOL, \
994
995
996
997
	.idVendor = (vend), \
	.idProduct = (prod), \
	.bInterfaceProtocol = (pr)

998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
/**
 * USB_DEVICE_INTERFACE_NUMBER - describe a usb device with a specific interface number
 * @vend: the 16 bit USB Vendor ID
 * @prod: the 16 bit USB Product ID
 * @num: bInterfaceNumber value
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific interface number of devices.
 */
#define USB_DEVICE_INTERFACE_NUMBER(vend, prod, num) \
	.match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
		       USB_DEVICE_ID_MATCH_INT_NUMBER, \
	.idVendor = (vend), \
	.idProduct = (prod), \
	.bInterfaceNumber = (num)

Linus Torvalds's avatar
Linus Torvalds committed
1014
1015
1016
1017
1018
1019
1020
1021
1022
/**
 * USB_DEVICE_INFO - macro used to describe a class of usb devices
 * @cl: bDeviceClass value
 * @sc: bDeviceSubClass value
 * @pr: bDeviceProtocol value
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific class of devices.
 */
1023
1024
1025
1026
1027
#define USB_DEVICE_INFO(cl, sc, pr) \
	.match_flags = USB_DEVICE_ID_MATCH_DEV_INFO, \
	.bDeviceClass = (cl), \
	.bDeviceSubClass = (sc), \
	.bDeviceProtocol = (pr)
Linus Torvalds's avatar
Linus Torvalds committed
1028
1029

/**
1030
 * USB_INTERFACE_INFO - macro used to describe a class of usb interfaces
Linus Torvalds's avatar
Linus Torvalds committed
1031
1032
1033
1034
1035
1036
1037
 * @cl: bInterfaceClass value
 * @sc: bInterfaceSubClass value
 * @pr: bInterfaceProtocol value
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific class of interfaces.
 */
1038
1039
1040
1041
1042
#define USB_INTERFACE_INFO(cl, sc, pr) \
	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO, \
	.bInterfaceClass = (cl), \
	.bInterfaceSubClass = (sc), \
	.bInterfaceProtocol = (pr)
1043
1044

/**
Randy Dunlap's avatar
Randy Dunlap committed
1045
 * USB_DEVICE_AND_INTERFACE_INFO - describe a specific usb device with a class of usb interfaces
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
 * @vend: the 16 bit USB Vendor ID
 * @prod: the 16 bit USB Product ID
 * @cl: bInterfaceClass value
 * @sc: bInterfaceSubClass value
 * @pr: bInterfaceProtocol value
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific device with a specific class of interfaces.
 *
 * This is especially useful when explicitly matching devices that have
 * vendor specific bDeviceClass values, but standards-compliant interfaces.
 */
1058
#define USB_DEVICE_AND_INTERFACE_INFO(vend, prod, cl, sc, pr) \
1059
1060
	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
		| USB_DEVICE_ID_MATCH_DEVICE, \
1061
1062
	.idVendor = (vend), \
	.idProduct = (prod), \
1063
	.bInterfaceClass = (cl), \
1064
1065
	.bInterfaceSubClass = (sc), \
	.bInterfaceProtocol = (pr)
Linus Torvalds's avatar
Linus Torvalds committed
1066

1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
/**
 * USB_VENDOR_AND_INTERFACE_INFO - describe a specific usb vendor with a class of usb interfaces
 * @vend: the 16 bit USB Vendor ID
 * @cl: bInterfaceClass value
 * @sc: bInterfaceSubClass value
 * @pr: bInterfaceProtocol value
 *
 * This macro is used to create a struct usb_device_id that matches a
 * specific vendor with a specific class of interfaces.
 *
 * This is especially useful when explicitly matching devices that have
 * vendor specific bDeviceClass values, but standards-compliant interfaces.
 */
#define USB_VENDOR_AND_INTERFACE_INFO(vend, cl, sc, pr) \
	.match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
		| USB_DEVICE_ID_MATCH_VENDOR, \
	.idVendor = (vend), \
	.bInterfaceClass = (cl), \
	.bInterfaceSubClass = (sc), \
	.bInterfaceProtocol = (pr)

1088
/* ----------------------------------------------------------------------- */
Linus Torvalds's avatar
Linus Torvalds committed
1089

1090
/* Stuff for dynamic usb ids */
1091
1092
1093
1094
1095
struct usb_dynids {
	spinlock_t lock;
	struct list_head list;
};

1096
1097
1098
1099
1100
1101
struct usb_dynid {
	struct list_head node;
	struct usb_device_id id;
};

extern ssize_t usb_store_new_id(struct usb_dynids *dynids,
1102
				const struct usb_device_id *id_table,
1103
1104
1105
				struct device_driver *driver,
				const char *buf, size_t count);

1106
1107
extern ssize_t usb_show_dynids(struct usb_dynids *dynids, char *buf);

Linus Torvalds's avatar
Linus Torvalds committed
1108
/**
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
 * struct usbdrv_wrap - wrapper for driver-model structure
 * @driver: The driver-model core driver structure.
 * @for_devices: Non-zero for device drivers, 0 for interface drivers.
 */
struct usbdrv_wrap {
	struct device_driver driver;
	int for_devices;
};

/**
 * struct usb_driver - identifies USB interface driver to usbcore
Linus Torvalds's avatar
Linus Torvalds committed
1120
1121
1122
1123
 * @name: The driver name should be unique among USB drivers,
 *	and should normally be the same as the module name.
 * @probe: Called to see if the driver is willing to manage a particular
 *	interface on a device.  If it is, probe returns zero and uses
1124
 *	usb_set_intfdata() to associate driver-specific data with the
Linus Torvalds's avatar
Linus Torvalds committed
1125
1126
 *	interface.  It may also use usb_set_interface() to specify the
 *	appropriate altsetting.  If unwilling to manage the interface,
Lucas De Marchi's avatar
Lucas De Marchi committed
1127
 *	return -ENODEV, if genuine IO errors occurred, an appropriate
1128
 *	negative errno value.
Linus Torvalds's avatar
Linus Torvalds committed
1129
1130
1131
 * @disconnect: Called when the interface is no longer accessible, usually
 *	because its device has been (or is being) disconnected or the
 *	driver module is being unloaded.
1132
 * @unlocked_ioctl: Used for drivers that want to talk to userspace through
Linus Torvalds's avatar
Linus Torvalds committed
1133
1134
1135
 *	the "usbfs" filesystem.  This lets devices provide ways to
 *	expose information to user space regardless of where they
 *	do (or don't) show up otherwise in the filesystem.
1136
1137
1138
1139
1140
1141
 * @suspend: Called when the device is going to be suspended by the
 *	system either from system sleep or runtime suspend context. The
 *	return value will be ignored in system sleep context, so do NOT
 *	try to continue using the device if suspend fails in this case.
 *	Instead, let the resume or reset-resume routine recover from
 *	the failure.
Linus Torvalds's avatar
Linus Torvalds committed
1142
 * @resume: Called when the device is being resumed by the system.
Alan Stern's avatar
Alan Stern committed
1143
1144
 * @reset_resume: Called when the suspended device has been reset instead
 *	of being resumed.
1145
1146
1147
1148
 * @pre_reset: Called by usb_reset_device() when the device is about to be
 *	reset.  This routine must not return until the driver has no active
 *	URBs for the device, and no more URBs may be submitted until the
 *	post_reset method is called.
1149
 * @post_reset: Called by usb_reset_device() after the device
1150
 *	has been reset
Linus Torvalds's avatar
Linus Torvalds committed
1151
1152
1153
 * @id_table: USB drivers use ID table to support hotplugging.
 *	Export this with MODULE_DEVICE_TABLE(usb,...).  This must be set
 *	or your driver's probe function will never get called.
1154
1155
 * @dynids: used internally to hold the list of dynamically added device
 *	ids for this driver.
1156
 * @drvwrap: Driver-model core structure wrapper.
1157
1158
 * @no_dynamic_id: if set to 1, the USB core will not allow dynamic ids to be
 *	added to this driver by preventing the sysfs file from being created.
1159
1160
 * @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
 *	for interfaces bound to this driver.
Alan Stern's avatar
Alan Stern committed
1161
1162
 * @soft_unbind: if set to 1, the USB core will not kill URBs and disable
 *	endpoints before calling the driver's disconnect method.
1163
 * @disable_hub_initiated_lpm: if set to 1, the USB core will not allow hubs
1164
1165
 *	to initiate lower power link state transitions when an idle timeout
 *	occurs.  Device-initiated USB 3.0 link PM will still be allowed.
Linus Torvalds's avatar
Linus Torvalds committed
1166
 *
1167
1168
 * USB interface drivers must provide a name, probe() and disconnect()
 * methods, and an id_table.  Other driver fields are optional.
Linus Torvalds's avatar
Linus Torvalds committed
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
 *
 * The id_table is used in hotplugging.  It holds a set of descriptors,
 * and specialized data may be associated with each entry.  That table
 * is used by both user and kernel mode hotplugging support.
 *
 * The probe() and disconnect() methods are called in a context where
 * they can sleep, but they should avoid abusing the privilege.  Most
 * work to connect to a device should be done when the device is opened,
 * and undone at the last close.  The disconnect code needs to address
 * concurrency issues with respect to open() and close() methods, as
 * well as forcing all pending I/O requests to complete (by unlinking
 * them as necessary, and blocking until the unlinks complete).
 */
struct usb_driver {
	const char *name;

	int (*probe) (struct usb_interface *intf,
		      const struct usb_device_id *id);

	void (*disconnect) (struct usb_interface *intf);

1190
	int (*unlocked_ioctl) (struct usb_interface *intf, unsigned int code,
1191
			void *buf);
Linus Torvalds's avatar
Linus Torvalds committed
1192

1193
	int (*suspend) (struct usb_interface *intf, pm_message_t message);
Linus Torvalds's avatar
Linus Torvalds committed
1194
	int (*resume) (struct usb_interface *intf);
Alan Stern's avatar
Alan Stern committed
1195
	int (*reset_resume)(struct usb_interface *intf);
Linus Torvalds's avatar
Linus Torvalds committed
1196

Alan Stern's avatar
Alan Stern committed
1197
1198
	int (*pre_reset)(struct usb_interface *intf);
	int (*post_reset)(struct usb_interface *intf);
1199

Linus Torvalds's avatar
Linus Torvalds committed
1200
1201
	const struct usb_device_id *id_table;

1202
	struct usb_dynids dynids;
1203
	struct usbdrv_wrap drvwrap;
1204
	unsigned int no_dynamic_id:1;
1205
	unsigned int supports_autosuspend:1;
1206
	unsigned int disable_hub_initiated_lpm:1;
Alan Stern's avatar
Alan Stern committed
1207
	unsigned int soft_unbind:1;
Linus Torvalds's avatar
Linus Torvalds committed
1208
};
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
#define	to_usb_driver(d) container_of(d, struct usb_driver, drvwrap.driver)

/**
 * struct usb_device_driver - identifies USB device driver to usbcore
 * @name: The driver name should be unique among USB drivers,
 *	and should normally be the same as the module name.
 * @probe: Called to see if the driver is willing to manage a particular
 *	device.  If it is, probe returns zero and uses dev_set_drvdata()
 *	to associate driver-specific data with the device.  If unwilling
 *	to manage the device, return a negative errno value.
 * @disconnect: Called when the device is no longer accessible, usually
 *	because it has been (or is being) disconnected or the driver's
 *	module is being unloaded.
 * @suspend: Called when the device is going to be suspended by the system.
 * @resume: Called when the device is being resumed by the system.
 * @drvwrap: Driver-model core structure wrapper.
1225
1226
 * @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
 *	for devices bound to this driver.
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
 *
 * USB drivers must provide all the fields listed above except drvwrap.
 */
struct usb_device_driver {
	const char *name;

	int (*probe) (struct usb_device *udev);
	void (*disconnect) (struct usb_device *udev);

	int (*suspend) (struct usb_device *udev, pm_message_t message);
1237
	int (*resume) (struct usb_device *udev, pm_message_t message);
1238
	struct usbdrv_wrap drvwrap;
1239
	unsigned int supports_autosuspend:1;
1240
1241
1242
};
#define	to_usb_device_driver(d) container_of(d, struct usb_device_driver, \
		drvwrap.driver)
Linus Torvalds's avatar
Linus Torvalds committed
1243
1244
1245
1246
1247

extern struct bus_type usb_bus_type;

/**
 * struct usb_class_driver - identifies a USB driver that wants to use the USB major number
1248
 * @name: the usb class device name for this driver.  Will show up in sysfs.
1249
 * @devnode: Callback to provide a naming hint for a possible
1250
 *	device node to create.
Linus Torvalds's avatar
Linus Torvalds committed
1251
1252
1253
1254
 * @fops: pointer to the struct file_operations of this driver.
 * @minor_base: the start of the minor range for this driver.
 *
 * This structure is used for the usb_register_dev() and
1255
 * usb_deregister_dev() functions, to consolidate a number of the
Linus Torvalds's avatar
Linus Torvalds committed
1256
1257
1258
1259
 * parameters used for them.
 */
struct usb_class_driver {
	char *name;
1260
	char *(*devnode)(struct device *dev, umode_t *mode);
1261
	const struct file_operations *fops;
1262
	int minor_base;
Linus Torvalds's avatar
Linus Torvalds committed
1263
1264
1265
1266
1267
1268
};

/*
 * use these in module_init()/module_exit()
 * and don't forget MODULE_DEVICE_TABLE(usb, ...)
 */
1269
1270
extern int usb_register_driver(struct usb_driver *, struct module *,
			       const char *);
1271
1272
1273
1274
1275

/* use a define to avoid include chaining to get THIS_MODULE & friends */
#define usb_register(driver) \
	usb_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)

Linus Torvalds's avatar
Linus Torvalds committed
1276
1277
extern void usb_deregister(struct usb_driver *);

1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
/**
 * module_usb_driver() - Helper macro for registering a USB driver
 * @__usb_driver: usb_driver struct
 *
 * Helper macro for USB drivers which do not do anything special in module
 * init/exit. This eliminates a lot of boilerplate. Each module may only
 * use this macro once, and calling it replaces module_init() and module_exit()
 */
#define module_usb_driver(__usb_driver) \
	module_driver(__usb_driver, usb_register, \
		       usb_deregister)

1290
1291
1292
1293
extern int usb_register_device_driver(struct usb_device_driver *,
			struct module *);
extern void usb_deregister_device_driver(struct usb_device_driver *);

Linus Torvalds's avatar
Linus Torvalds committed
1294
1295
1296
1297
1298
1299
1300
extern int usb_register_dev(struct usb_interface *intf,
			    struct usb_class_driver *class_driver);
extern void usb_deregister_dev(struct usb_interface *intf,
			       struct usb_class_driver *class_driver);

extern int usb_disabled(void);

1301
/* ----------------------------------------------------------------------- */
Linus Torvalds's avatar
Linus Torvalds committed
1302
1303
1304
1305
1306
1307
1308

/*
 * URB support, for asynchronous request completions
 */

/*
 * urb->transfer_flags:
1309
1310
 *
 * Note: URB_DIR_IN/OUT is automatically set in usb_submit_urb().
Linus Torvalds's avatar
Linus Torvalds committed
1311
1312
 */
#define URB_SHORT_NOT_OK	0x0001	/* report short reads as errors */
1313
1314
#define URB_ISO_ASAP		0x0002	/* iso-only; use the first unexpired
					 * slot in the schedule */
Linus Torvalds's avatar
Linus Torvalds committed
1315
#define URB_NO_TRANSFER_DMA_MAP	0x0004	/* urb->transfer_dma valid on submit */
1316
1317
1318
#define URB_ZERO_PACKET		0x0040	/* Finish bulk OUT with short packet */
#define URB_NO_INTERRUPT	0x0080	/* HINT: no non-error interrupt
					 * needed */
1319
#define URB_FREE_BUFFER		0x0100	/* Free transfer buffer with the URB */
Linus Torvalds's avatar
Linus Torvalds committed
1320

1321
/* The following flags are used internally by usbcore and HCDs */
1322
1323
1324
1325
#define URB_DIR_IN		0x0200	/* Transfer from device to host */
#define URB_DIR_OUT		0
#define URB_DIR_MASK		URB_DIR_IN

1326
1327
1328
1329
1330
1331
1332
#define URB_DMA_MAP_SINGLE	0x00010000	/* Non-scatter-gather mapping */
#define URB_DMA_MAP_PAGE	0x00020000	/* HCD-unsupported S-G */
#define URB_DMA_MAP_SG		0x00040000	/* HCD-supported S-G */
#define URB_MAP_LOCAL		0x00080000	/* HCD-local-memory mapping */
#define URB_SETUP_MAP_SINGLE	0x00100000	/* Setup packet DMA mapped */
#define URB_SETUP_MAP_LOCAL	0x00200000	/* HCD-local setup packet */
#define URB_DMA_SG_COMBINED	0x00400000	/* S-G entries were combined */
1333
#define URB_ALIGNED_TEMP_BUFFER	0x00800000	/* Temp buffer was alloc'd */
1334

Linus Torvalds's avatar
Linus Torvalds committed
1335
1336
1337
1338
struct usb_iso_packet_descriptor {
	unsigned int offset;
	unsigned int length;		/* expected length */
	unsigned int actual_length;
1339
	int status;
Linus Torvalds's avatar
Linus Torvalds committed
1340
1341
1342
1343
};

struct urb;