1b2441318SGreg Kroah-Hartman /* SPDX-License-Identifier: GPL-2.0 */
21da177e4SLinus Torvalds #ifndef __LINUX_USB_H
31da177e4SLinus Torvalds #define __LINUX_USB_H
41da177e4SLinus Torvalds
51da177e4SLinus Torvalds #include <linux/mod_devicetable.h>
65f848137SDavid Brownell #include <linux/usb/ch9.h>
71da177e4SLinus Torvalds
81da177e4SLinus Torvalds #define USB_MAJOR 180
9fbf82fd2SKay Sievers #define USB_DEVICE_MAJOR 189
101da177e4SLinus Torvalds
111da177e4SLinus Torvalds
121da177e4SLinus Torvalds #ifdef __KERNEL__
131da177e4SLinus Torvalds
141da177e4SLinus Torvalds #include <linux/errno.h> /* for -ENODEV */
151da177e4SLinus Torvalds #include <linux/delay.h> /* for mdelay() */
161da177e4SLinus Torvalds #include <linux/interrupt.h> /* for in_interrupt() */
171da177e4SLinus Torvalds #include <linux/list.h> /* for struct list_head */
181da177e4SLinus Torvalds #include <linux/kref.h> /* for struct kref */
191da177e4SLinus Torvalds #include <linux/device.h> /* for struct device */
201da177e4SLinus Torvalds #include <linux/fs.h> /* for struct file_operations */
211da177e4SLinus Torvalds #include <linux/completion.h> /* for struct completion */
221da177e4SLinus Torvalds #include <linux/sched.h> /* for current && schedule_timeout */
23645daaabSAlan Stern #include <linux/mutex.h> /* for struct mutex */
246ddf27cdSMing Lei #include <linux/pm_runtime.h> /* for runtime PM */
251da177e4SLinus Torvalds
261da177e4SLinus Torvalds struct usb_device;
271da177e4SLinus Torvalds struct usb_driver;
281da177e4SLinus Torvalds
291da177e4SLinus Torvalds /*-------------------------------------------------------------------------*/
301da177e4SLinus Torvalds
311da177e4SLinus Torvalds /*
321da177e4SLinus Torvalds * Host-side wrappers for standard USB descriptors ... these are parsed
331da177e4SLinus Torvalds * from the data provided by devices. Parsing turns them from a flat
341da177e4SLinus Torvalds * sequence of descriptors into a hierarchy:
351da177e4SLinus Torvalds *
361da177e4SLinus Torvalds * - devices have one (usually) or more configs;
371da177e4SLinus Torvalds * - configs have one (often) or more interfaces;
381da177e4SLinus Torvalds * - interfaces have one (usually) or more settings;
391da177e4SLinus Torvalds * - each interface setting has zero or (usually) more endpoints.
40663c30d0SSarah Sharp * - a SuperSpeed endpoint has a companion descriptor
411da177e4SLinus Torvalds *
421da177e4SLinus Torvalds * And there might be other descriptors mixed in with those.
431da177e4SLinus Torvalds *
441da177e4SLinus Torvalds * Devices may also have class-specific or vendor-specific descriptors.
451da177e4SLinus Torvalds */
461da177e4SLinus Torvalds
479bde7497SGreg Kroah-Hartman struct ep_device;
489bde7497SGreg Kroah-Hartman
491da177e4SLinus Torvalds /**
501da177e4SLinus Torvalds * struct usb_host_endpoint - host-side endpoint descriptor and queue
511da177e4SLinus Torvalds * @desc: descriptor for this endpoint, wMaxPacketSize in native byteorder
52842f1690SAlan Stern * @ss_ep_comp: SuperSpeed companion descriptor for this endpoint
53b37d83a6SMathias Nyman * @ssp_isoc_ep_comp: SuperSpeedPlus isoc companion descriptor for this endpoint
541da177e4SLinus Torvalds * @urb_list: urbs queued to this endpoint; maintained by usbcore
551da177e4SLinus Torvalds * @hcpriv: for use by HCD; typically holds hardware dma queue head (QH)
561da177e4SLinus Torvalds * with one or more transfer descriptors (TDs) per urb
577fac9a33SRandy Dunlap * @ep_dev: ep_device for sysfs info
581da177e4SLinus Torvalds * @extra: descriptors following this endpoint in the configuration
591da177e4SLinus Torvalds * @extralen: how many bytes of "extra" are valid
60bdd016baSAlan Stern * @enabled: URBs may be submitted to this endpoint
618d4f70b2SHans de Goede * @streams: number of USB-3 streams allocated on the endpoint
621da177e4SLinus Torvalds *
631da177e4SLinus Torvalds * USB requests are always queued to a given endpoint, identified by a
641da177e4SLinus Torvalds * descriptor within an active interface in a given USB configuration.
651da177e4SLinus Torvalds */
661da177e4SLinus Torvalds struct usb_host_endpoint {
671da177e4SLinus Torvalds struct usb_endpoint_descriptor desc;
68842f1690SAlan Stern struct usb_ss_ep_comp_descriptor ss_ep_comp;
69b37d83a6SMathias Nyman struct usb_ssp_isoc_ep_comp_descriptor ssp_isoc_ep_comp;
701da177e4SLinus Torvalds struct list_head urb_list;
711da177e4SLinus Torvalds void *hcpriv;
729bde7497SGreg Kroah-Hartman struct ep_device *ep_dev; /* For sysfs info */
731da177e4SLinus Torvalds
741da177e4SLinus Torvalds unsigned char *extra; /* Extra descriptors */
751da177e4SLinus Torvalds int extralen;
76bdd016baSAlan Stern int enabled;
778d4f70b2SHans de Goede int streams;
781da177e4SLinus Torvalds };
791da177e4SLinus Torvalds
801da177e4SLinus Torvalds /* host-side wrapper for one interface setting's parsed descriptors */
811da177e4SLinus Torvalds struct usb_host_interface {
821da177e4SLinus Torvalds struct usb_interface_descriptor desc;
831da177e4SLinus Torvalds
840d5ff306SRichard Kennedy int extralen;
850d5ff306SRichard Kennedy unsigned char *extra; /* Extra descriptors */
860d5ff306SRichard Kennedy
879636c378SChris Rorvick /* array of desc.bNumEndpoints endpoints associated with this
881da177e4SLinus Torvalds * interface setting. these will be in no particular order.
891da177e4SLinus Torvalds */
901da177e4SLinus Torvalds struct usb_host_endpoint *endpoint;
911da177e4SLinus Torvalds
921da177e4SLinus Torvalds char *string; /* iInterface string, if present */
931da177e4SLinus Torvalds };
941da177e4SLinus Torvalds
951da177e4SLinus Torvalds enum usb_interface_condition {
961da177e4SLinus Torvalds USB_INTERFACE_UNBOUND = 0,
971da177e4SLinus Torvalds USB_INTERFACE_BINDING,
981da177e4SLinus Torvalds USB_INTERFACE_BOUND,
991da177e4SLinus Torvalds USB_INTERFACE_UNBINDING,
1001da177e4SLinus Torvalds };
1011da177e4SLinus Torvalds
10266a35939SJohan Hovold int __must_check
10366a35939SJohan Hovold usb_find_common_endpoints(struct usb_host_interface *alt,
10466a35939SJohan Hovold struct usb_endpoint_descriptor **bulk_in,
10566a35939SJohan Hovold struct usb_endpoint_descriptor **bulk_out,
10666a35939SJohan Hovold struct usb_endpoint_descriptor **int_in,
10766a35939SJohan Hovold struct usb_endpoint_descriptor **int_out);
10866a35939SJohan Hovold
109279daf4eSJohan Hovold int __must_check
110279daf4eSJohan Hovold usb_find_common_endpoints_reverse(struct usb_host_interface *alt,
111279daf4eSJohan Hovold struct usb_endpoint_descriptor **bulk_in,
112279daf4eSJohan Hovold struct usb_endpoint_descriptor **bulk_out,
113279daf4eSJohan Hovold struct usb_endpoint_descriptor **int_in,
114279daf4eSJohan Hovold struct usb_endpoint_descriptor **int_out);
115279daf4eSJohan Hovold
11666a35939SJohan Hovold static inline int __must_check
usb_find_bulk_in_endpoint(struct usb_host_interface * alt,struct usb_endpoint_descriptor ** bulk_in)11766a35939SJohan Hovold usb_find_bulk_in_endpoint(struct usb_host_interface *alt,
11866a35939SJohan Hovold struct usb_endpoint_descriptor **bulk_in)
11966a35939SJohan Hovold {
12066a35939SJohan Hovold return usb_find_common_endpoints(alt, bulk_in, NULL, NULL, NULL);
12166a35939SJohan Hovold }
12266a35939SJohan Hovold
12366a35939SJohan Hovold static inline int __must_check
usb_find_bulk_out_endpoint(struct usb_host_interface * alt,struct usb_endpoint_descriptor ** bulk_out)12466a35939SJohan Hovold usb_find_bulk_out_endpoint(struct usb_host_interface *alt,
12566a35939SJohan Hovold struct usb_endpoint_descriptor **bulk_out)
12666a35939SJohan Hovold {
12766a35939SJohan Hovold return usb_find_common_endpoints(alt, NULL, bulk_out, NULL, NULL);
12866a35939SJohan Hovold }
12966a35939SJohan Hovold
13066a35939SJohan Hovold static inline int __must_check
usb_find_int_in_endpoint(struct usb_host_interface * alt,struct usb_endpoint_descriptor ** int_in)13166a35939SJohan Hovold usb_find_int_in_endpoint(struct usb_host_interface *alt,
13266a35939SJohan Hovold struct usb_endpoint_descriptor **int_in)
13366a35939SJohan Hovold {
13466a35939SJohan Hovold return usb_find_common_endpoints(alt, NULL, NULL, int_in, NULL);
13566a35939SJohan Hovold }
13666a35939SJohan Hovold
13766a35939SJohan Hovold static inline int __must_check
usb_find_int_out_endpoint(struct usb_host_interface * alt,struct usb_endpoint_descriptor ** int_out)13866a35939SJohan Hovold usb_find_int_out_endpoint(struct usb_host_interface *alt,
13966a35939SJohan Hovold struct usb_endpoint_descriptor **int_out)
14066a35939SJohan Hovold {
14166a35939SJohan Hovold return usb_find_common_endpoints(alt, NULL, NULL, NULL, int_out);
14266a35939SJohan Hovold }
14366a35939SJohan Hovold
144279daf4eSJohan Hovold static inline int __must_check
usb_find_last_bulk_in_endpoint(struct usb_host_interface * alt,struct usb_endpoint_descriptor ** bulk_in)145279daf4eSJohan Hovold usb_find_last_bulk_in_endpoint(struct usb_host_interface *alt,
146279daf4eSJohan Hovold struct usb_endpoint_descriptor **bulk_in)
147279daf4eSJohan Hovold {
148279daf4eSJohan Hovold return usb_find_common_endpoints_reverse(alt, bulk_in, NULL, NULL, NULL);
149279daf4eSJohan Hovold }
150279daf4eSJohan Hovold
151279daf4eSJohan Hovold static inline int __must_check
usb_find_last_bulk_out_endpoint(struct usb_host_interface * alt,struct usb_endpoint_descriptor ** bulk_out)152279daf4eSJohan Hovold usb_find_last_bulk_out_endpoint(struct usb_host_interface *alt,
153279daf4eSJohan Hovold struct usb_endpoint_descriptor **bulk_out)
154279daf4eSJohan Hovold {
155279daf4eSJohan Hovold return usb_find_common_endpoints_reverse(alt, NULL, bulk_out, NULL, NULL);
156279daf4eSJohan Hovold }
157279daf4eSJohan Hovold
158279daf4eSJohan Hovold static inline int __must_check
usb_find_last_int_in_endpoint(struct usb_host_interface * alt,struct usb_endpoint_descriptor ** int_in)159279daf4eSJohan Hovold usb_find_last_int_in_endpoint(struct usb_host_interface *alt,
160279daf4eSJohan Hovold struct usb_endpoint_descriptor **int_in)
161279daf4eSJohan Hovold {
162279daf4eSJohan Hovold return usb_find_common_endpoints_reverse(alt, NULL, NULL, int_in, NULL);
163279daf4eSJohan Hovold }
164279daf4eSJohan Hovold
165279daf4eSJohan Hovold static inline int __must_check
usb_find_last_int_out_endpoint(struct usb_host_interface * alt,struct usb_endpoint_descriptor ** int_out)166279daf4eSJohan Hovold usb_find_last_int_out_endpoint(struct usb_host_interface *alt,
167279daf4eSJohan Hovold struct usb_endpoint_descriptor **int_out)
168279daf4eSJohan Hovold {
169279daf4eSJohan Hovold return usb_find_common_endpoints_reverse(alt, NULL, NULL, NULL, int_out);
170279daf4eSJohan Hovold }
171279daf4eSJohan Hovold
172f98e0640SBastien Nocera enum usb_wireless_status {
173f98e0640SBastien Nocera USB_WIRELESS_STATUS_NA = 0,
174f98e0640SBastien Nocera USB_WIRELESS_STATUS_DISCONNECTED,
175f98e0640SBastien Nocera USB_WIRELESS_STATUS_CONNECTED,
176f98e0640SBastien Nocera };
177f98e0640SBastien Nocera
1781da177e4SLinus Torvalds /**
1791da177e4SLinus Torvalds * struct usb_interface - what usb device drivers talk to
1801da177e4SLinus Torvalds * @altsetting: array of interface structures, one for each alternate
1811da177e4SLinus Torvalds * setting that may be selected. Each one includes a set of
1821da177e4SLinus Torvalds * endpoint configurations. They will be in no particular order.
1831da177e4SLinus Torvalds * @cur_altsetting: the current altsetting.
184d6d914f5SLei Ming * @num_altsetting: number of altsettings defined.
1853f423787SRandy Dunlap * @intf_assoc: interface association descriptor
1861da177e4SLinus Torvalds * @minor: the minor number assigned to this interface, if this
1871da177e4SLinus Torvalds * interface is bound to a driver that uses the USB major number.
1881da177e4SLinus Torvalds * If this interface does not use the USB major, this field should
1891da177e4SLinus Torvalds * be unused. The driver should set this value in the probe()
1901da177e4SLinus Torvalds * function of the driver, after it has been assigned a minor
1911da177e4SLinus Torvalds * number from the USB core by calling usb_register_dev().
1921da177e4SLinus Torvalds * @condition: binding state of the interface: not bound, binding
1931da177e4SLinus Torvalds * (in probe()), bound to a driver, or unbinding (in disconnect())
194f88ed90dSRandy Dunlap * @sysfs_files_created: sysfs attributes exist
1953b23dd6fSAlan Stern * @ep_devs_created: endpoint child pseudo-devices exist
196352d0263SAlan Stern * @unregistering: flag set when the interface is being unregistered
197645daaabSAlan Stern * @needs_remote_wakeup: flag set when the driver requires remote-wakeup
198645daaabSAlan Stern * capability during autosuspend.
19955151d7dSAlan Stern * @needs_altsetting0: flag set when a set-interface request for altsetting 0
20055151d7dSAlan Stern * has been deferred.
201f4f4d587SAlan Stern * @needs_binding: flag set when the driver should be re-probed or unbound
202f4f4d587SAlan Stern * following a reset or suspend operation it doesn't support.
20307294cc2SStefan Koch * @authorized: This allows to (de)authorize individual interfaces instead
20407294cc2SStefan Koch * a whole device in contrast to the device authorization.
205539adfedSBastien Nocera * @wireless_status: if the USB device uses a receiver/emitter combo, whether
206539adfedSBastien Nocera * the emitter is connected.
207539adfedSBastien Nocera * @wireless_status_work: Used for scheduling wireless status changes
208539adfedSBastien Nocera * from atomic context.
2091da177e4SLinus Torvalds * @dev: driver model's view of this device
2100873c764SGreg Kroah-Hartman * @usb_dev: if an interface is bound to the USB major, this will point
2110873c764SGreg Kroah-Hartman * to the sysfs representation for that device.
212dc023dceSInaky Perez-Gonzalez * @reset_ws: Used for scheduling resets from atomic context.
213c6ba1c2aSRandy Dunlap * @resetting_device: USB core reset the device, so use alt setting 0 as
214c6ba1c2aSRandy Dunlap * current; needs bandwidth alloc after reset.
2151da177e4SLinus Torvalds *
2161da177e4SLinus Torvalds * USB device drivers attach to interfaces on a physical device. Each
2171da177e4SLinus Torvalds * interface encapsulates a single high level function, such as feeding
2181da177e4SLinus Torvalds * an audio stream to a speaker or reporting a change in a volume control.
2191da177e4SLinus Torvalds * Many USB devices only have one interface. The protocol used to talk to
2201da177e4SLinus Torvalds * an interface's endpoints can be defined in a usb "class" specification,
2211da177e4SLinus Torvalds * or by a product's vendor. The (default) control endpoint is part of
2221da177e4SLinus Torvalds * every interface, but is never listed among the interface's descriptors.
2231da177e4SLinus Torvalds *
2241da177e4SLinus Torvalds * The driver that is bound to the interface can use standard driver model
2251da177e4SLinus Torvalds * calls such as dev_get_drvdata() on the dev member of this structure.
2261da177e4SLinus Torvalds *
2271da177e4SLinus Torvalds * Each interface may have alternate settings. The initial configuration
2281da177e4SLinus Torvalds * of a device sets altsetting 0, but the device driver can change
2291da177e4SLinus Torvalds * that setting using usb_set_interface(). Alternate settings are often
23059c51591SMichael Opdenacker * used to control the use of periodic endpoints, such as by having
2311da177e4SLinus Torvalds * different endpoints use different amounts of reserved USB bandwidth.
2321da177e4SLinus Torvalds * All standards-conformant USB devices that use isochronous endpoints
2331da177e4SLinus Torvalds * will use them in non-default settings.
2341da177e4SLinus Torvalds *
2351da177e4SLinus Torvalds * The USB specification says that alternate setting numbers must run from
2361da177e4SLinus Torvalds * 0 to one less than the total number of alternate settings. But some
2371da177e4SLinus Torvalds * devices manage to mess this up, and the structures aren't necessarily
2381da177e4SLinus Torvalds * stored in numerical order anyhow. Use usb_altnum_to_altsetting() to
2391da177e4SLinus Torvalds * look up an alternate setting in the altsetting array based on its number.
2401da177e4SLinus Torvalds */
2411da177e4SLinus Torvalds struct usb_interface {
2421da177e4SLinus Torvalds /* array of alternate settings for this interface,
2431da177e4SLinus Torvalds * stored in no particular order */
2441da177e4SLinus Torvalds struct usb_host_interface *altsetting;
2451da177e4SLinus Torvalds
2461da177e4SLinus Torvalds struct usb_host_interface *cur_altsetting; /* the currently
2471da177e4SLinus Torvalds * active alternate setting */
2481da177e4SLinus Torvalds unsigned num_altsetting; /* number of alternate settings */
2491da177e4SLinus Torvalds
250165fe97eSCraig W. Nadler /* If there is an interface association descriptor then it will list
251165fe97eSCraig W. Nadler * the associated interfaces */
252165fe97eSCraig W. Nadler struct usb_interface_assoc_descriptor *intf_assoc;
253165fe97eSCraig W. Nadler
254b724ae77SAlan Stern int minor; /* minor number this interface is
255b724ae77SAlan Stern * bound to */
2561da177e4SLinus Torvalds enum usb_interface_condition condition; /* state of binding */
2577e61559fSAlan Stern unsigned sysfs_files_created:1; /* the sysfs attributes exist */
2583b23dd6fSAlan Stern unsigned ep_devs_created:1; /* endpoint "devices" exist */
259352d0263SAlan Stern unsigned unregistering:1; /* unregistration is in progress */
260645daaabSAlan Stern unsigned needs_remote_wakeup:1; /* driver requires remote wakeup */
26155151d7dSAlan Stern unsigned needs_altsetting0:1; /* switch to altsetting 0 is pending */
26278d9a487SAlan Stern unsigned needs_binding:1; /* needs delayed unbind/rebind */
26304a723eaSSarah Sharp unsigned resetting_device:1; /* true: bandwidth alloc after reset */
2644ad2ddceSStefan Koch unsigned authorized:1; /* used for interface authorization */
265f98e0640SBastien Nocera enum usb_wireless_status wireless_status;
2660a4db185SBastien Nocera struct work_struct wireless_status_work;
2674d064c08SAlan Stern
2681da177e4SLinus Torvalds struct device dev; /* interface specific device info */
269969ab2eeSGreg Kroah-Hartman struct device *usb_dev;
270dc023dceSInaky Perez-Gonzalez struct work_struct reset_ws; /* for resets in atomic context */
2711da177e4SLinus Torvalds };
272593efa40SGreg Kroah-Hartman
273c3da6792SGreg Kroah-Hartman #define to_usb_interface(__dev) container_of_const(__dev, struct usb_interface, dev)
2741da177e4SLinus Torvalds
usb_get_intfdata(struct usb_interface * intf)2751da177e4SLinus Torvalds static inline void *usb_get_intfdata(struct usb_interface *intf)
2761da177e4SLinus Torvalds {
2771da177e4SLinus Torvalds return dev_get_drvdata(&intf->dev);
2781da177e4SLinus Torvalds }
2791da177e4SLinus Torvalds
28027ef1784SVincent Mailhol /**
28111cefeb2SJohan Hovold * usb_set_intfdata() - associate driver-specific data with an interface
28211cefeb2SJohan Hovold * @intf: USB interface
28311cefeb2SJohan Hovold * @data: driver data
28427ef1784SVincent Mailhol *
28511cefeb2SJohan Hovold * Drivers can use this function in their probe() callbacks to associate
28611cefeb2SJohan Hovold * driver-specific data with an interface.
28727ef1784SVincent Mailhol *
28811cefeb2SJohan Hovold * Note that there is generally no need to clear the driver-data pointer even
28911cefeb2SJohan Hovold * if some drivers do so for historical or implementation-specific reasons.
29027ef1784SVincent Mailhol */
usb_set_intfdata(struct usb_interface * intf,void * data)2911da177e4SLinus Torvalds static inline void usb_set_intfdata(struct usb_interface *intf, void *data)
2921da177e4SLinus Torvalds {
2931da177e4SLinus Torvalds dev_set_drvdata(&intf->dev, data);
2941da177e4SLinus Torvalds }
2951da177e4SLinus Torvalds
2961da177e4SLinus Torvalds struct usb_interface *usb_get_intf(struct usb_interface *intf);
2971da177e4SLinus Torvalds void usb_put_intf(struct usb_interface *intf);
2981da177e4SLinus Torvalds
2998f5d3544SHans de Goede /* Hard limit */
3008f5d3544SHans de Goede #define USB_MAXENDPOINTS 30
3011da177e4SLinus Torvalds /* this maximum is arbitrary */
3021da177e4SLinus Torvalds #define USB_MAXINTERFACES 32
303812219abSGreg Kroah-Hartman #define USB_MAXIADS (USB_MAXINTERFACES/2)
3041da177e4SLinus Torvalds
305*13890626SAlan Stern bool usb_check_bulk_endpoints(
306*13890626SAlan Stern const struct usb_interface *intf, const u8 *ep_addrs);
307*13890626SAlan Stern bool usb_check_int_endpoints(
308*13890626SAlan Stern const struct usb_interface *intf, const u8 *ep_addrs);
309*13890626SAlan Stern
31062f0342dSFelipe Balbi /*
31162f0342dSFelipe Balbi * USB Resume Timer: Every Host controller driver should drive the resume
31262f0342dSFelipe Balbi * signalling on the bus for the amount of time defined by this macro.
31362f0342dSFelipe Balbi *
31462f0342dSFelipe Balbi * That way we will have a 'stable' behavior among all HCDs supported by Linux.
31562f0342dSFelipe Balbi *
31662f0342dSFelipe Balbi * Note that the USB Specification states we should drive resume for *at least*
31762f0342dSFelipe Balbi * 20 ms, but it doesn't give an upper bound. This creates two possible
31862f0342dSFelipe Balbi * situations which we want to avoid:
31962f0342dSFelipe Balbi *
32062f0342dSFelipe Balbi * (a) sometimes an msleep(20) might expire slightly before 20 ms, which causes
32162f0342dSFelipe Balbi * us to fail USB Electrical Tests, thus failing Certification
32262f0342dSFelipe Balbi *
32362f0342dSFelipe Balbi * (b) Some (many) devices actually need more than 20 ms of resume signalling,
32462f0342dSFelipe Balbi * and while we can argue that's against the USB Specification, we don't have
32562f0342dSFelipe Balbi * control over which devices a certification laboratory will be using for
32662f0342dSFelipe Balbi * certification. If CertLab uses a device which was tested against Windows and
32762f0342dSFelipe Balbi * that happens to have relaxed resume signalling rules, we might fall into
32862f0342dSFelipe Balbi * situations where we fail interoperability and electrical tests.
32962f0342dSFelipe Balbi *
33062f0342dSFelipe Balbi * In order to avoid both conditions, we're using a 40 ms resume timeout, which
33162f0342dSFelipe Balbi * should cope with both LPJ calibration errors and devices not following every
33262f0342dSFelipe Balbi * detail of the USB Specification.
33362f0342dSFelipe Balbi */
33462f0342dSFelipe Balbi #define USB_RESUME_TIMEOUT 40 /* ms */
33562f0342dSFelipe Balbi
3361da177e4SLinus Torvalds /**
3371da177e4SLinus Torvalds * struct usb_interface_cache - long-term representation of a device interface
3381da177e4SLinus Torvalds * @num_altsetting: number of altsettings defined.
3391da177e4SLinus Torvalds * @ref: reference counter.
3401da177e4SLinus Torvalds * @altsetting: variable-length array of interface structures, one for
3411da177e4SLinus Torvalds * each alternate setting that may be selected. Each one includes a
3421da177e4SLinus Torvalds * set of endpoint configurations. They will be in no particular order.
3431da177e4SLinus Torvalds *
3441da177e4SLinus Torvalds * These structures persist for the lifetime of a usb_device, unlike
3451da177e4SLinus Torvalds * struct usb_interface (which persists only as long as its configuration
3461da177e4SLinus Torvalds * is installed). The altsetting arrays can be accessed through these
3471da177e4SLinus Torvalds * structures at any time, permitting comparison of configurations and
34821470e32SMauro Carvalho Chehab * providing support for the /sys/kernel/debug/usb/devices pseudo-file.
3491da177e4SLinus Torvalds */
3501da177e4SLinus Torvalds struct usb_interface_cache {
3511da177e4SLinus Torvalds unsigned num_altsetting; /* number of alternate settings */
3521da177e4SLinus Torvalds struct kref ref; /* reference counter */
3531da177e4SLinus Torvalds
3541da177e4SLinus Torvalds /* variable-length array of alternate settings for this interface,
3551da177e4SLinus Torvalds * stored in no particular order */
3566bc3f397SGustavo A. R. Silva struct usb_host_interface altsetting[];
3571da177e4SLinus Torvalds };
3581da177e4SLinus Torvalds #define ref_to_usb_interface_cache(r) \
3591da177e4SLinus Torvalds container_of(r, struct usb_interface_cache, ref)
3601da177e4SLinus Torvalds #define altsetting_to_usb_interface_cache(a) \
3611da177e4SLinus Torvalds container_of(a, struct usb_interface_cache, altsetting[0])
3621da177e4SLinus Torvalds
3631da177e4SLinus Torvalds /**
3641da177e4SLinus Torvalds * struct usb_host_config - representation of a device's configuration
3651da177e4SLinus Torvalds * @desc: the device's configuration descriptor.
3661da177e4SLinus Torvalds * @string: pointer to the cached version of the iConfiguration string, if
3671da177e4SLinus Torvalds * present for this configuration.
3683f423787SRandy Dunlap * @intf_assoc: list of any interface association descriptors in this config
3691da177e4SLinus Torvalds * @interface: array of pointers to usb_interface structures, one for each
3701da177e4SLinus Torvalds * interface in the configuration. The number of interfaces is stored
3711da177e4SLinus Torvalds * in desc.bNumInterfaces. These pointers are valid only while the
372ded071f4SRandy Dunlap * configuration is active.
3731da177e4SLinus Torvalds * @intf_cache: array of pointers to usb_interface_cache structures, one
3741da177e4SLinus Torvalds * for each interface in the configuration. These structures exist
3751da177e4SLinus Torvalds * for the entire life of the device.
3761da177e4SLinus Torvalds * @extra: pointer to buffer containing all extra descriptors associated
3771da177e4SLinus Torvalds * with this configuration (those preceding the first interface
3781da177e4SLinus Torvalds * descriptor).
3791da177e4SLinus Torvalds * @extralen: length of the extra descriptors buffer.
3801da177e4SLinus Torvalds *
3811da177e4SLinus Torvalds * USB devices may have multiple configurations, but only one can be active
3821da177e4SLinus Torvalds * at any time. Each encapsulates a different operational environment;
3831da177e4SLinus Torvalds * for example, a dual-speed device would have separate configurations for
3841da177e4SLinus Torvalds * full-speed and high-speed operation. The number of configurations
3851da177e4SLinus Torvalds * available is stored in the device descriptor as bNumConfigurations.
3861da177e4SLinus Torvalds *
3871da177e4SLinus Torvalds * A configuration can contain multiple interfaces. Each corresponds to
3881da177e4SLinus Torvalds * a different function of the USB device, and all are available whenever
3891da177e4SLinus Torvalds * the configuration is active. The USB standard says that interfaces
3901da177e4SLinus Torvalds * are supposed to be numbered from 0 to desc.bNumInterfaces-1, but a lot
3911da177e4SLinus Torvalds * of devices get this wrong. In addition, the interface array is not
3921da177e4SLinus Torvalds * guaranteed to be sorted in numerical order. Use usb_ifnum_to_if() to
3931da177e4SLinus Torvalds * look up an interface entry based on its number.
3941da177e4SLinus Torvalds *
3951da177e4SLinus Torvalds * Device drivers should not attempt to activate configurations. The choice
3961da177e4SLinus Torvalds * of which configuration to install is a policy decision based on such
3971da177e4SLinus Torvalds * considerations as available power, functionality provided, and the user's
398312c004dSKay Sievers * desires (expressed through userspace tools). However, drivers can call
3991da177e4SLinus Torvalds * usb_reset_configuration() to reinitialize the current configuration and
4001da177e4SLinus Torvalds * all its interfaces.
4011da177e4SLinus Torvalds */
4021da177e4SLinus Torvalds struct usb_host_config {
4031da177e4SLinus Torvalds struct usb_config_descriptor desc;
4041da177e4SLinus Torvalds
4054f62efe6SAlan Stern char *string; /* iConfiguration string, if present */
406165fe97eSCraig W. Nadler
407165fe97eSCraig W. Nadler /* List of any Interface Association Descriptors in this
408165fe97eSCraig W. Nadler * configuration. */
409165fe97eSCraig W. Nadler struct usb_interface_assoc_descriptor *intf_assoc[USB_MAXIADS];
410165fe97eSCraig W. Nadler
4111da177e4SLinus Torvalds /* the interfaces associated with this configuration,
4121da177e4SLinus Torvalds * stored in no particular order */
4131da177e4SLinus Torvalds struct usb_interface *interface[USB_MAXINTERFACES];
4141da177e4SLinus Torvalds
4151da177e4SLinus Torvalds /* Interface information available even when this is not the
4161da177e4SLinus Torvalds * active configuration */
4171da177e4SLinus Torvalds struct usb_interface_cache *intf_cache[USB_MAXINTERFACES];
4181da177e4SLinus Torvalds
4191da177e4SLinus Torvalds unsigned char *extra; /* Extra descriptors */
4201da177e4SLinus Torvalds int extralen;
4211da177e4SLinus Torvalds };
4221da177e4SLinus Torvalds
4233148bf04SAndiry Xu /* USB2.0 and USB3.0 device BOS descriptor set */
4243148bf04SAndiry Xu struct usb_host_bos {
4253148bf04SAndiry Xu struct usb_bos_descriptor *desc;
4263148bf04SAndiry Xu
4273148bf04SAndiry Xu struct usb_ext_cap_descriptor *ext_cap;
4283148bf04SAndiry Xu struct usb_ss_cap_descriptor *ss_cap;
4293220befdSMathias Nyman struct usb_ssp_cap_descriptor *ssp_cap;
4303148bf04SAndiry Xu struct usb_ss_container_id_descriptor *ss_id;
431faee822cSMathias Nyman struct usb_ptm_cap_descriptor *ptm_cap;
4323148bf04SAndiry Xu };
4333148bf04SAndiry Xu
4341da177e4SLinus Torvalds int __usb_get_extra_descriptor(char *buffer, unsigned size,
435704620afSMathias Payer unsigned char type, void **ptr, size_t min);
4361da177e4SLinus Torvalds #define usb_get_extra_descriptor(ifpoint, type, ptr) \
437969ab2eeSGreg Kroah-Hartman __usb_get_extra_descriptor((ifpoint)->extra, \
438969ab2eeSGreg Kroah-Hartman (ifpoint)->extralen, \
439704620afSMathias Payer type, (void **)ptr, sizeof(**(ptr)))
4401da177e4SLinus Torvalds
441b724ae77SAlan Stern /* ----------------------------------------------------------------------- */
4421da177e4SLinus Torvalds
4431da177e4SLinus Torvalds /* USB device number allocation bitmap */
4441da177e4SLinus Torvalds struct usb_devmap {
4451da177e4SLinus Torvalds unsigned long devicemap[128 / (8*sizeof(unsigned long))];
4461da177e4SLinus Torvalds };
4471da177e4SLinus Torvalds
4481da177e4SLinus Torvalds /*
4491da177e4SLinus Torvalds * Allocated per bus (tree of devices) we have:
4501da177e4SLinus Torvalds */
4511da177e4SLinus Torvalds struct usb_bus {
452c8d141ceSGreg Kroah-Hartman struct device *controller; /* host side hardware */
453a8c06e40SArnd Bergmann struct device *sysdev; /* as seen from firmware or bus */
4541da177e4SLinus Torvalds int busnum; /* Bus number (in order of reg) */
4551b26da15SGreg Kroah-Hartman const char *bus_name; /* stable id (PCI slot_name etc) */
45607a8cdd2SAnand Gadiyar u8 uses_pio_for_control; /*
45707a8cdd2SAnand Gadiyar * Does the host controller use PIO
45807a8cdd2SAnand Gadiyar * for control transfers?
45907a8cdd2SAnand Gadiyar */
4601da177e4SLinus Torvalds u8 otg_port; /* 0, or number of OTG/HNP port */
4611da177e4SLinus Torvalds unsigned is_b_host:1; /* true during some HNP roleswitches */
4621da177e4SLinus Torvalds unsigned b_hnp_enable:1; /* OTG: did A-Host enable HNP? */
46319181bc5SHans de Goede unsigned no_stop_on_short:1; /*
46419181bc5SHans de Goede * Quirk: some controllers don't stop
46519181bc5SHans de Goede * the ep queue on a short transfer
46619181bc5SHans de Goede * with the URB_SHORT_NOT_OK flag set.
46719181bc5SHans de Goede */
468bcc48f1aSMing Lei unsigned no_sg_constraint:1; /* no sg constraint */
4694c1bd3d7SDavid Vrabel unsigned sg_tablesize; /* 0 or largest number of sg list entries */
4701da177e4SLinus Torvalds
471b724ae77SAlan Stern int devnum_next; /* Next open device number in
472b724ae77SAlan Stern * round-robin allocation */
473feb26ac3SChris Bainbridge struct mutex devnum_next_mutex; /* devnum_next mutex */
4741da177e4SLinus Torvalds
4751da177e4SLinus Torvalds struct usb_devmap devmap; /* device address allocation map */
4761da177e4SLinus Torvalds struct usb_device *root_hub; /* Root hub */
4776d19c009SAlan Stern struct usb_bus *hs_companion; /* Companion EHCI bus, if any */
4781da177e4SLinus Torvalds
4791da177e4SLinus Torvalds int bandwidth_allocated; /* on this bus: how much of the time
4801da177e4SLinus Torvalds * reserved for periodic (intr/iso)
4811da177e4SLinus Torvalds * requests is used, on average?
4821da177e4SLinus Torvalds * Units: microseconds/frame.
4831da177e4SLinus Torvalds * Limits: Full/low speed reserve 90%,
4841da177e4SLinus Torvalds * while high speed reserves 80%.
4851da177e4SLinus Torvalds */
4861da177e4SLinus Torvalds int bandwidth_int_reqs; /* number of Interrupt requests */
4871da177e4SLinus Torvalds int bandwidth_isoc_reqs; /* number of Isoc. requests */
4881da177e4SLinus Torvalds
489da0aa716SAlan Stern unsigned resuming_ports; /* bit array: resuming root-hub ports */
490da0aa716SAlan Stern
491f150fa1aSPete Zaitcev #if defined(CONFIG_USB_MON) || defined(CONFIG_USB_MON_MODULE)
4921da177e4SLinus Torvalds struct mon_bus *mon_bus; /* non-null when associated */
4931da177e4SLinus Torvalds int monitored; /* non-zero when monitored */
4941da177e4SLinus Torvalds #endif
4951da177e4SLinus Torvalds };
4961da177e4SLinus Torvalds
4979b6f0c4bSValentina Manea struct usb_dev_state;
4986080cd0eSValentina Manea
499b724ae77SAlan Stern /* ----------------------------------------------------------------------- */
5001da177e4SLinus Torvalds
5011da177e4SLinus Torvalds struct usb_tt;
5021da177e4SLinus Torvalds
50305f91689SLan Tianyu enum usb_port_connect_type {
50405f91689SLan Tianyu USB_PORT_CONNECT_TYPE_UNKNOWN = 0,
50505f91689SLan Tianyu USB_PORT_CONNECT_TYPE_HOT_PLUG,
50605f91689SLan Tianyu USB_PORT_CONNECT_TYPE_HARD_WIRED,
50705f91689SLan Tianyu USB_PORT_NOT_USED,
50805f91689SLan Tianyu };
50905f91689SLan Tianyu
51051e0a012SSarah Sharp /*
51125244227SNicolas Boichat * USB port quirks.
51225244227SNicolas Boichat */
51325244227SNicolas Boichat
51425244227SNicolas Boichat /* For the given port, prefer the old (faster) enumeration scheme. */
51525244227SNicolas Boichat #define USB_PORT_QUIRK_OLD_SCHEME BIT(0)
51625244227SNicolas Boichat
517aa071a92SNicolas Boichat /* Decrease TRSTRCY to 10ms during device enumeration. */
518aa071a92SNicolas Boichat #define USB_PORT_QUIRK_FAST_ENUM BIT(1)
519aa071a92SNicolas Boichat
52025244227SNicolas Boichat /*
52117f34867SMathias Nyman * USB 2.0 Link Power Management (LPM) parameters.
52217f34867SMathias Nyman */
52317f34867SMathias Nyman struct usb2_lpm_parameters {
52417f34867SMathias Nyman /* Best effort service latency indicate how long the host will drive
52517f34867SMathias Nyman * resume on an exit from L1.
52617f34867SMathias Nyman */
52717f34867SMathias Nyman unsigned int besl;
52817f34867SMathias Nyman
52917f34867SMathias Nyman /* Timeout value in microseconds for the L1 inactivity (LPM) timer.
53017f34867SMathias Nyman * When the timer counts to zero, the parent hub will initiate a LPM
53117f34867SMathias Nyman * transition to L1.
53217f34867SMathias Nyman */
53317f34867SMathias Nyman int timeout;
53417f34867SMathias Nyman };
53517f34867SMathias Nyman
53617f34867SMathias Nyman /*
53751e0a012SSarah Sharp * USB 3.0 Link Power Management (LPM) parameters.
53851e0a012SSarah Sharp *
53951e0a012SSarah Sharp * PEL and SEL are USB 3.0 Link PM latencies for device-initiated LPM exit.
54051e0a012SSarah Sharp * MEL is the USB 3.0 Link PM latency for host-initiated LPM exit.
54151e0a012SSarah Sharp * All three are stored in nanoseconds.
54251e0a012SSarah Sharp */
54351e0a012SSarah Sharp struct usb3_lpm_parameters {
54451e0a012SSarah Sharp /*
54551e0a012SSarah Sharp * Maximum exit latency (MEL) for the host to send a packet to the
54651e0a012SSarah Sharp * device (either a Ping for isoc endpoints, or a data packet for
54751e0a012SSarah Sharp * interrupt endpoints), the hubs to decode the packet, and for all hubs
54851e0a012SSarah Sharp * in the path to transition the links to U0.
54951e0a012SSarah Sharp */
55051e0a012SSarah Sharp unsigned int mel;
55151e0a012SSarah Sharp /*
55251e0a012SSarah Sharp * Maximum exit latency for a device-initiated LPM transition to bring
55351e0a012SSarah Sharp * all links into U0. Abbreviated as "PEL" in section 9.4.12 of the USB
55451e0a012SSarah Sharp * 3.0 spec, with no explanation of what "P" stands for. "Path"?
55551e0a012SSarah Sharp */
55651e0a012SSarah Sharp unsigned int pel;
55751e0a012SSarah Sharp
55851e0a012SSarah Sharp /*
55951e0a012SSarah Sharp * The System Exit Latency (SEL) includes PEL, and three other
56051e0a012SSarah Sharp * latencies. After a device initiates a U0 transition, it will take
56151e0a012SSarah Sharp * some time from when the device sends the ERDY to when it will finally
56251e0a012SSarah Sharp * receive the data packet. Basically, SEL should be the worse-case
56351e0a012SSarah Sharp * latency from when a device starts initiating a U0 transition to when
56451e0a012SSarah Sharp * it will get data.
56551e0a012SSarah Sharp */
56651e0a012SSarah Sharp unsigned int sel;
5671ea7e0e8SSarah Sharp /*
5681ea7e0e8SSarah Sharp * The idle timeout value that is currently programmed into the parent
5691ea7e0e8SSarah Sharp * hub for this device. When the timer counts to zero, the parent hub
5701ea7e0e8SSarah Sharp * will initiate an LPM transition to either U1 or U2.
5711ea7e0e8SSarah Sharp */
5721ea7e0e8SSarah Sharp int timeout;
57351e0a012SSarah Sharp };
57451e0a012SSarah Sharp
575f476fbabSRandy Dunlap /**
5761da177e4SLinus Torvalds * struct usb_device - kernel's representation of a USB device
577f476fbabSRandy Dunlap * @devnum: device number; address on a USB bus
578f476fbabSRandy Dunlap * @devpath: device ID string for use in messages (e.g., /port/...)
5797206b001SSarah Sharp * @route: tree topology hex string for use with xHCI
580f476fbabSRandy Dunlap * @state: device state: configured, not attached, etc.
581f476fbabSRandy Dunlap * @speed: device speed: high/full/low (or error)
582013eedb8SMathias Nyman * @rx_lanes: number of rx lanes in use, USB 3.2 adds dual-lane support
583013eedb8SMathias Nyman * @tx_lanes: number of tx lanes in use, USB 3.2 adds dual-lane support
5840299809bSThinh Nguyen * @ssp_rate: SuperSpeed Plus phy signaling rate and lane count
585f476fbabSRandy Dunlap * @tt: Transaction Translator info; used with low/full speed dev, highspeed hub
586f476fbabSRandy Dunlap * @ttport: device port on that tt hub
587f476fbabSRandy Dunlap * @toggle: one bit for each endpoint, with ([0] = IN, [1] = OUT) endpoints
588f476fbabSRandy Dunlap * @parent: our hub, unless we're the root
589f476fbabSRandy Dunlap * @bus: bus we're part of
590f476fbabSRandy Dunlap * @ep0: endpoint 0 data (default control pipe)
591f476fbabSRandy Dunlap * @dev: generic device interface
592f476fbabSRandy Dunlap * @descriptor: USB device descriptor
5933148bf04SAndiry Xu * @bos: USB device BOS descriptor set
594f476fbabSRandy Dunlap * @config: all of the device's configs
595f476fbabSRandy Dunlap * @actconfig: the active configuration
596f476fbabSRandy Dunlap * @ep_in: array of IN endpoints
597f476fbabSRandy Dunlap * @ep_out: array of OUT endpoints
598f476fbabSRandy Dunlap * @rawdescriptors: raw descriptors for each config
599f476fbabSRandy Dunlap * @bus_mA: Current available from the bus
600f476fbabSRandy Dunlap * @portnum: parent port number (origin 1)
601f476fbabSRandy Dunlap * @level: number of USB hub ancestors
6024998f1efSJim Lin * @devaddr: device address, XHCI: assigned by HW, others: same as devnum
603f476fbabSRandy Dunlap * @can_submit: URBs may be submitted
604f476fbabSRandy Dunlap * @persist_enabled: USB_PERSIST enabled for this device
6059c6d7788SAlan Stern * @reset_in_progress: the device is being reset
606f476fbabSRandy Dunlap * @have_langid: whether string_langid is valid
607f476fbabSRandy Dunlap * @authorized: policy has said we can use it;
608f476fbabSRandy Dunlap * (user space) policy determines if we authorize this device to be
609f476fbabSRandy Dunlap * used or not. By default, wired USB devices are authorized.
610f476fbabSRandy Dunlap * WUSB devices are not, until we authorize them from user space.
611f476fbabSRandy Dunlap * FIXME -- complete doc
6123b52f128SInaky Perez-Gonzalez * @authenticated: Crypto authentication passed
6131ff4df56SAndiry Xu * @lpm_capable: device supports LPM
614e146caf3SMathias Nyman * @lpm_devinit_allow: Allow USB3 device initiated LPM, exit latency is in range
61565580b43SAndiry Xu * @usb2_hw_lpm_capable: device can perform USB2 hardware LPM
616a558ccdcSMathias Nyman * @usb2_hw_lpm_besl_capable: device can perform USB2 hardware BESL LPM
617de68bab4SSarah Sharp * @usb2_hw_lpm_enabled: USB2 hardware LPM is enabled
618de68bab4SSarah Sharp * @usb2_hw_lpm_allowed: Userspace allows USB 2.0 LPM to be enabled
619bf5ce5bfSLu Baolu * @usb3_lpm_u1_enabled: USB3 hardware U1 LPM enabled
620bf5ce5bfSLu Baolu * @usb3_lpm_u2_enabled: USB3 hardware U2 LPM enabled
621f476fbabSRandy Dunlap * @string_langid: language ID for strings
622f476fbabSRandy Dunlap * @product: iProduct string, if present (static)
623f476fbabSRandy Dunlap * @manufacturer: iManufacturer string, if present (static)
624f476fbabSRandy Dunlap * @serial: iSerialNumber string, if present (static)
625f476fbabSRandy Dunlap * @filelist: usbfs files that are open to this device
626f476fbabSRandy Dunlap * @maxchild: number of ports if hub
627f476fbabSRandy Dunlap * @quirks: quirks of the whole device
628f476fbabSRandy Dunlap * @urbnum: number of URBs submitted for the whole device
629f476fbabSRandy Dunlap * @active_duration: total time device is not suspended
630f476fbabSRandy Dunlap * @connect_time: time device was first connected
631f476fbabSRandy Dunlap * @do_remote_wakeup: remote wakeup should be enabled
632f476fbabSRandy Dunlap * @reset_resume: needs reset instead of resume
633bfd1e910SAlan Stern * @port_is_suspended: the upstream port is suspended (L2 or U3)
634c6515272SSarah Sharp * @slot_id: Slot ID assigned by xHCI
6350846e7e9SMatthew Garrett * @removable: Device can be physically removed from this port
63617f34867SMathias Nyman * @l1_params: best effor service latency for USB2 L1 LPM state, and L1 timeout.
6371ea7e0e8SSarah Sharp * @u1_params: exit latencies for USB3 U1 LPM state, and hub-initiated timeout.
6381ea7e0e8SSarah Sharp * @u2_params: exit latencies for USB3 U2 LPM state, and hub-initiated timeout.
6391ea7e0e8SSarah Sharp * @lpm_disable_count: Ref count used by usb_disable_lpm() and usb_enable_lpm()
6401ea7e0e8SSarah Sharp * to keep track of the number of functions that require USB 3.0 Link Power
6411ea7e0e8SSarah Sharp * Management to be disabled for this usb_device. This count should only
6421ea7e0e8SSarah Sharp * be manipulated by those functions, with the bandwidth_mutex is held.
643886ee36eSFelipe Balbi * @hub_delay: cached value consisting of:
644886ee36eSFelipe Balbi * parent->hub_delay + wHubDelay + tTPTransmissionDelay (40ns)
645886ee36eSFelipe Balbi * Will be used as wValue for SetIsochDelay requests.
64643ff9869SRandy Dunlap * @use_generic_driver: ask driver core to reprobe using the generic driver.
6471da177e4SLinus Torvalds *
648f476fbabSRandy Dunlap * Notes:
6491da177e4SLinus Torvalds * Usbcore drivers should not set usbdev->state directly. Instead use
6501da177e4SLinus Torvalds * usb_set_device_state().
6511da177e4SLinus Torvalds */
6521da177e4SLinus Torvalds struct usb_device {
653f476fbabSRandy Dunlap int devnum;
654f476fbabSRandy Dunlap char devpath[16];
6557206b001SSarah Sharp u32 route;
656f476fbabSRandy Dunlap enum usb_device_state state;
657f476fbabSRandy Dunlap enum usb_device_speed speed;
658013eedb8SMathias Nyman unsigned int rx_lanes;
659013eedb8SMathias Nyman unsigned int tx_lanes;
6600299809bSThinh Nguyen enum usb_ssp_rate ssp_rate;
6611da177e4SLinus Torvalds
662f476fbabSRandy Dunlap struct usb_tt *tt;
663f476fbabSRandy Dunlap int ttport;
6641da177e4SLinus Torvalds
665f476fbabSRandy Dunlap unsigned int toggle[2];
6661da177e4SLinus Torvalds
667f476fbabSRandy Dunlap struct usb_device *parent;
668f476fbabSRandy Dunlap struct usb_bus *bus;
6691da177e4SLinus Torvalds struct usb_host_endpoint ep0;
6701da177e4SLinus Torvalds
671f476fbabSRandy Dunlap struct device dev;
6721da177e4SLinus Torvalds
673f476fbabSRandy Dunlap struct usb_device_descriptor descriptor;
6743148bf04SAndiry Xu struct usb_host_bos *bos;
675f476fbabSRandy Dunlap struct usb_host_config *config;
6761da177e4SLinus Torvalds
677f476fbabSRandy Dunlap struct usb_host_config *actconfig;
6781da177e4SLinus Torvalds struct usb_host_endpoint *ep_in[16];
6791da177e4SLinus Torvalds struct usb_host_endpoint *ep_out[16];
6801da177e4SLinus Torvalds
681f476fbabSRandy Dunlap char **rawdescriptors;
6821da177e4SLinus Torvalds
683f476fbabSRandy Dunlap unsigned short bus_mA;
684f476fbabSRandy Dunlap u8 portnum;
685f476fbabSRandy Dunlap u8 level;
6864998f1efSJim Lin u8 devaddr;
68755c52718SAlan Stern
688f476fbabSRandy Dunlap unsigned can_submit:1;
689f476fbabSRandy Dunlap unsigned persist_enabled:1;
6909c6d7788SAlan Stern unsigned reset_in_progress:1;
691f476fbabSRandy Dunlap unsigned have_langid:1;
692f476fbabSRandy Dunlap unsigned authorized:1;
6933b52f128SInaky Perez-Gonzalez unsigned authenticated:1;
6941ff4df56SAndiry Xu unsigned lpm_capable:1;
695e146caf3SMathias Nyman unsigned lpm_devinit_allow:1;
69665580b43SAndiry Xu unsigned usb2_hw_lpm_capable:1;
697a558ccdcSMathias Nyman unsigned usb2_hw_lpm_besl_capable:1;
69865580b43SAndiry Xu unsigned usb2_hw_lpm_enabled:1;
699de68bab4SSarah Sharp unsigned usb2_hw_lpm_allowed:1;
700bf5ce5bfSLu Baolu unsigned usb3_lpm_u1_enabled:1;
701bf5ce5bfSLu Baolu unsigned usb3_lpm_u2_enabled:1;
702f476fbabSRandy Dunlap int string_langid;
7031da177e4SLinus Torvalds
7044f62efe6SAlan Stern /* static strings from the device */
705f476fbabSRandy Dunlap char *product;
706f476fbabSRandy Dunlap char *manufacturer;
707f476fbabSRandy Dunlap char *serial;
7084f62efe6SAlan Stern
7091da177e4SLinus Torvalds struct list_head filelist;
7101da177e4SLinus Torvalds
711f476fbabSRandy Dunlap int maxchild;
712645daaabSAlan Stern
713f476fbabSRandy Dunlap u32 quirks;
714f476fbabSRandy Dunlap atomic_t urbnum;
715b5e795f8SAlan Stern
716f476fbabSRandy Dunlap unsigned long active_duration;
71715123006SSarah Sharp
718f476fbabSRandy Dunlap unsigned long connect_time;
719b5e795f8SAlan Stern
720f476fbabSRandy Dunlap unsigned do_remote_wakeup:1;
721f476fbabSRandy Dunlap unsigned reset_resume:1;
722bfd1e910SAlan Stern unsigned port_is_suspended:1;
723130eac41SArnd Bergmann
724c6515272SSarah Sharp int slot_id;
72517f34867SMathias Nyman struct usb2_lpm_parameters l1_params;
72651e0a012SSarah Sharp struct usb3_lpm_parameters u1_params;
72751e0a012SSarah Sharp struct usb3_lpm_parameters u2_params;
7281ea7e0e8SSarah Sharp unsigned lpm_disable_count;
729886ee36eSFelipe Balbi
730886ee36eSFelipe Balbi u16 hub_delay;
73177419aa4SBastien Nocera unsigned use_generic_driver:1;
7321da177e4SLinus Torvalds };
7331da177e4SLinus Torvalds
734c3da6792SGreg Kroah-Hartman #define to_usb_device(__dev) container_of_const(__dev, struct usb_device, dev)
735593efa40SGreg Kroah-Hartman
__intf_to_usbdev(struct usb_interface * intf)736593efa40SGreg Kroah-Hartman static inline struct usb_device *__intf_to_usbdev(struct usb_interface *intf)
7371e429018SMatthew Wilcox {
7381e429018SMatthew Wilcox return to_usb_device(intf->dev.parent);
7391e429018SMatthew Wilcox }
__intf_to_usbdev_const(const struct usb_interface * intf)740593efa40SGreg Kroah-Hartman static inline const struct usb_device *__intf_to_usbdev_const(const struct usb_interface *intf)
741593efa40SGreg Kroah-Hartman {
742593efa40SGreg Kroah-Hartman return to_usb_device((const struct device *)intf->dev.parent);
743593efa40SGreg Kroah-Hartman }
744593efa40SGreg Kroah-Hartman
745593efa40SGreg Kroah-Hartman #define interface_to_usbdev(intf) \
746593efa40SGreg Kroah-Hartman _Generic((intf), \
747593efa40SGreg Kroah-Hartman const struct usb_interface *: __intf_to_usbdev_const, \
748593efa40SGreg Kroah-Hartman struct usb_interface *: __intf_to_usbdev)(intf)
7491e429018SMatthew Wilcox
7501da177e4SLinus Torvalds extern struct usb_device *usb_get_dev(struct usb_device *dev);
7511da177e4SLinus Torvalds extern void usb_put_dev(struct usb_device *dev);
752ff823c79SLan Tianyu extern struct usb_device *usb_hub_find_child(struct usb_device *hdev,
753ff823c79SLan Tianyu int port1);
754ff823c79SLan Tianyu
755ff823c79SLan Tianyu /**
756ff823c79SLan Tianyu * usb_hub_for_each_child - iterate over all child devices on the hub
757ff823c79SLan Tianyu * @hdev: USB device belonging to the usb hub
758ff823c79SLan Tianyu * @port1: portnum associated with child device
759ff823c79SLan Tianyu * @child: child device pointer
760ff823c79SLan Tianyu */
761ff823c79SLan Tianyu #define usb_hub_for_each_child(hdev, port1, child) \
762ff823c79SLan Tianyu for (port1 = 1, child = usb_hub_find_child(hdev, port1); \
763ff823c79SLan Tianyu port1 <= hdev->maxchild; \
764969ddcfcSAlan Stern child = usb_hub_find_child(hdev, ++port1)) \
765969ddcfcSAlan Stern if (!child) continue; else
7661da177e4SLinus Torvalds
7679ad3d6ccSAlan Stern /* USB device locking */
7688e9394ceSGreg Kroah-Hartman #define usb_lock_device(udev) device_lock(&(udev)->dev)
7698e9394ceSGreg Kroah-Hartman #define usb_unlock_device(udev) device_unlock(&(udev)->dev)
7707dd9cba5SOliver Neukum #define usb_lock_device_interruptible(udev) device_lock_interruptible(&(udev)->dev)
7718e9394ceSGreg Kroah-Hartman #define usb_trylock_device(udev) device_trylock(&(udev)->dev)
7721da177e4SLinus Torvalds extern int usb_lock_device_for_reset(struct usb_device *udev,
773095bc335SLuiz Fernando N. Capitulino const struct usb_interface *iface);
7741da177e4SLinus Torvalds
7751da177e4SLinus Torvalds /* USB port reset for device reinitialization */
7761da177e4SLinus Torvalds extern int usb_reset_device(struct usb_device *dev);
777dc023dceSInaky Perez-Gonzalez extern void usb_queue_reset_device(struct usb_interface *dev);
7781da177e4SLinus Torvalds
779659ab7a4SThomas Zimmermann extern struct device *usb_intf_get_dma_device(struct usb_interface *intf);
780659ab7a4SThomas Zimmermann
781f7ac7787SLan Tianyu #ifdef CONFIG_ACPI
782f7ac7787SLan Tianyu extern int usb_acpi_set_power_state(struct usb_device *hdev, int index,
783f7ac7787SLan Tianyu bool enable);
784f7ac7787SLan Tianyu extern bool usb_acpi_power_manageable(struct usb_device *hdev, int index);
785cd702d18SMathias Nyman extern int usb_acpi_port_lpm_incapable(struct usb_device *hdev, int index);
786f7ac7787SLan Tianyu #else
usb_acpi_set_power_state(struct usb_device * hdev,int index,bool enable)787f7ac7787SLan Tianyu static inline int usb_acpi_set_power_state(struct usb_device *hdev, int index,
788f7ac7787SLan Tianyu bool enable) { return 0; }
usb_acpi_power_manageable(struct usb_device * hdev,int index)789f7ac7787SLan Tianyu static inline bool usb_acpi_power_manageable(struct usb_device *hdev, int index)
790f7ac7787SLan Tianyu { return true; }
usb_acpi_port_lpm_incapable(struct usb_device * hdev,int index)791cd702d18SMathias Nyman static inline int usb_acpi_port_lpm_incapable(struct usb_device *hdev, int index)
792cd702d18SMathias Nyman { return 0; }
793f7ac7787SLan Tianyu #endif
7941da177e4SLinus Torvalds
795645daaabSAlan Stern /* USB autosuspend and autoresume */
796ceb6c9c8SRafael J. Wysocki #ifdef CONFIG_PM
7979e18c821SAlan Stern extern void usb_enable_autosuspend(struct usb_device *udev);
7989e18c821SAlan Stern extern void usb_disable_autosuspend(struct usb_device *udev);
799088f7fecSAlan Stern
800645daaabSAlan Stern extern int usb_autopm_get_interface(struct usb_interface *intf);
801645daaabSAlan Stern extern void usb_autopm_put_interface(struct usb_interface *intf);
8029ac39f28SAlan Stern extern int usb_autopm_get_interface_async(struct usb_interface *intf);
8039ac39f28SAlan Stern extern void usb_autopm_put_interface_async(struct usb_interface *intf);
8049bbdf1e0SAlan Stern extern void usb_autopm_get_interface_no_resume(struct usb_interface *intf);
8059bbdf1e0SAlan Stern extern void usb_autopm_put_interface_no_suspend(struct usb_interface *intf);
806692a186cSAlan Stern
usb_mark_last_busy(struct usb_device * udev)8071941044aSAlan Stern static inline void usb_mark_last_busy(struct usb_device *udev)
8081941044aSAlan Stern {
8096ddf27cdSMing Lei pm_runtime_mark_last_busy(&udev->dev);
8101941044aSAlan Stern }
8111941044aSAlan Stern
812692a186cSAlan Stern #else
813692a186cSAlan Stern
usb_enable_autosuspend(struct usb_device * udev)814088f7fecSAlan Stern static inline int usb_enable_autosuspend(struct usb_device *udev)
815088f7fecSAlan Stern { return 0; }
usb_disable_autosuspend(struct usb_device * udev)816088f7fecSAlan Stern static inline int usb_disable_autosuspend(struct usb_device *udev)
817088f7fecSAlan Stern { return 0; }
818088f7fecSAlan Stern
usb_autopm_get_interface(struct usb_interface * intf)819692a186cSAlan Stern static inline int usb_autopm_get_interface(struct usb_interface *intf)
820692a186cSAlan Stern { return 0; }
usb_autopm_get_interface_async(struct usb_interface * intf)8219ac39f28SAlan Stern static inline int usb_autopm_get_interface_async(struct usb_interface *intf)
8229ac39f28SAlan Stern { return 0; }
8239ac39f28SAlan Stern
usb_autopm_put_interface(struct usb_interface * intf)824692a186cSAlan Stern static inline void usb_autopm_put_interface(struct usb_interface *intf)
825692a186cSAlan Stern { }
usb_autopm_put_interface_async(struct usb_interface * intf)8269ac39f28SAlan Stern static inline void usb_autopm_put_interface_async(struct usb_interface *intf)
8279ac39f28SAlan Stern { }
usb_autopm_get_interface_no_resume(struct usb_interface * intf)8288e4ceb38SAlan Stern static inline void usb_autopm_get_interface_no_resume(
8298e4ceb38SAlan Stern struct usb_interface *intf)
830692a186cSAlan Stern { }
usb_autopm_put_interface_no_suspend(struct usb_interface * intf)8318e4ceb38SAlan Stern static inline void usb_autopm_put_interface_no_suspend(
8328e4ceb38SAlan Stern struct usb_interface *intf)
833692a186cSAlan Stern { }
usb_mark_last_busy(struct usb_device * udev)8341941044aSAlan Stern static inline void usb_mark_last_busy(struct usb_device *udev)
8351941044aSAlan Stern { }
836692a186cSAlan Stern #endif
837645daaabSAlan Stern
838e9261fb6SSarah Sharp extern int usb_disable_lpm(struct usb_device *udev);
839e9261fb6SSarah Sharp extern void usb_enable_lpm(struct usb_device *udev);
840e9261fb6SSarah Sharp /* Same as above, but these functions lock/unlock the bandwidth_mutex. */
841e9261fb6SSarah Sharp extern int usb_unlocked_disable_lpm(struct usb_device *udev);
842e9261fb6SSarah Sharp extern void usb_unlocked_enable_lpm(struct usb_device *udev);
843e9261fb6SSarah Sharp
844f74631e3SSarah Sharp extern int usb_disable_ltm(struct usb_device *udev);
845f74631e3SSarah Sharp extern void usb_enable_ltm(struct usb_device *udev);
846f74631e3SSarah Sharp
usb_device_supports_ltm(struct usb_device * udev)847024f117cSSarah Sharp static inline bool usb_device_supports_ltm(struct usb_device *udev)
848024f117cSSarah Sharp {
849dd80b54bSOliver Neukum if (udev->speed < USB_SPEED_SUPER || !udev->bos || !udev->bos->ss_cap)
850024f117cSSarah Sharp return false;
851024f117cSSarah Sharp return udev->bos->ss_cap->bmAttributes & USB_LTM_SUPPORT;
852024f117cSSarah Sharp }
853024f117cSSarah Sharp
usb_device_no_sg_constraint(struct usb_device * udev)854bcc48f1aSMing Lei static inline bool usb_device_no_sg_constraint(struct usb_device *udev)
855bcc48f1aSMing Lei {
856bcc48f1aSMing Lei return udev && udev->bus && udev->bus->no_sg_constraint;
857bcc48f1aSMing Lei }
858bcc48f1aSMing Lei
859024f117cSSarah Sharp
8601da177e4SLinus Torvalds /*-------------------------------------------------------------------------*/
8611da177e4SLinus Torvalds
8621da177e4SLinus Torvalds /* for drivers using iso endpoints */
8631da177e4SLinus Torvalds extern int usb_get_current_frame_number(struct usb_device *usb_dev);
8641da177e4SLinus Torvalds
865eab1cafcSSarah Sharp /* Sets up a group of bulk endpoints to support multiple stream IDs. */
866eab1cafcSSarah Sharp extern int usb_alloc_streams(struct usb_interface *interface,
867eab1cafcSSarah Sharp struct usb_host_endpoint **eps, unsigned int num_eps,
868eab1cafcSSarah Sharp unsigned int num_streams, gfp_t mem_flags);
869eab1cafcSSarah Sharp
870eab1cafcSSarah Sharp /* Reverts a group of bulk endpoints back to not using stream IDs. */
8716c74dadaSHans de Goede extern int usb_free_streams(struct usb_interface *interface,
872eab1cafcSSarah Sharp struct usb_host_endpoint **eps, unsigned int num_eps,
873eab1cafcSSarah Sharp gfp_t mem_flags);
874eab1cafcSSarah Sharp
8751da177e4SLinus Torvalds /* used these for multi-interface device registration */
8761da177e4SLinus Torvalds extern int usb_driver_claim_interface(struct usb_driver *driver,
877aaadc6aeSJohan Hovold struct usb_interface *iface, void *data);
8781da177e4SLinus Torvalds
8791da177e4SLinus Torvalds /**
8801da177e4SLinus Torvalds * usb_interface_claimed - returns true iff an interface is claimed
8811da177e4SLinus Torvalds * @iface: the interface being checked
8821da177e4SLinus Torvalds *
883626f090cSYacine Belkadi * Return: %true (nonzero) iff the interface is claimed, else %false
884626f090cSYacine Belkadi * (zero).
885626f090cSYacine Belkadi *
886626f090cSYacine Belkadi * Note:
8871da177e4SLinus Torvalds * Callers must own the driver model's usb bus readlock. So driver
8881da177e4SLinus Torvalds * probe() entries don't need extra locking, but other call contexts
8891da177e4SLinus Torvalds * may need to explicitly claim that lock.
8901da177e4SLinus Torvalds *
8911da177e4SLinus Torvalds */
usb_interface_claimed(struct usb_interface * iface)892969ab2eeSGreg Kroah-Hartman static inline int usb_interface_claimed(struct usb_interface *iface)
893969ab2eeSGreg Kroah-Hartman {
8941da177e4SLinus Torvalds return (iface->dev.driver != NULL);
8951da177e4SLinus Torvalds }
8961da177e4SLinus Torvalds
8971da177e4SLinus Torvalds extern void usb_driver_release_interface(struct usb_driver *driver,
8981da177e4SLinus Torvalds struct usb_interface *iface);
8990a4db185SBastien Nocera
9000a4db185SBastien Nocera int usb_set_wireless_status(struct usb_interface *iface,
9010a4db185SBastien Nocera enum usb_wireless_status status);
9020a4db185SBastien Nocera
9031da177e4SLinus Torvalds const struct usb_device_id *usb_match_id(struct usb_interface *interface,
9041da177e4SLinus Torvalds const struct usb_device_id *id);
90593bacefcSGreg Kroah-Hartman extern int usb_match_one_id(struct usb_interface *interface,
90693bacefcSGreg Kroah-Hartman const struct usb_device_id *id);
9071da177e4SLinus Torvalds
9089b790915SJulius Werner extern int usb_for_each_dev(void *data, int (*fn)(struct usb_device *, void *));
9091da177e4SLinus Torvalds extern struct usb_interface *usb_find_interface(struct usb_driver *drv,
9101da177e4SLinus Torvalds int minor);
911095bc335SLuiz Fernando N. Capitulino extern struct usb_interface *usb_ifnum_to_if(const struct usb_device *dev,
9121da177e4SLinus Torvalds unsigned ifnum);
9131da177e4SLinus Torvalds extern struct usb_host_interface *usb_altnum_to_altsetting(
914095bc335SLuiz Fernando N. Capitulino const struct usb_interface *intf, unsigned int altnum);
91591017f9cSSarah Sharp extern struct usb_host_interface *usb_find_alt_setting(
91691017f9cSSarah Sharp struct usb_host_config *config,
91791017f9cSSarah Sharp unsigned int iface_num,
91891017f9cSSarah Sharp unsigned int alt_num);
9191da177e4SLinus Torvalds
9206080cd0eSValentina Manea /* port claiming functions */
9216080cd0eSValentina Manea int usb_hub_claim_port(struct usb_device *hdev, unsigned port1,
9229b6f0c4bSValentina Manea struct usb_dev_state *owner);
9236080cd0eSValentina Manea int usb_hub_release_port(struct usb_device *hdev, unsigned port1,
9249b6f0c4bSValentina Manea struct usb_dev_state *owner);
9251da177e4SLinus Torvalds
9261da177e4SLinus Torvalds /**
9271da177e4SLinus Torvalds * usb_make_path - returns stable device path in the usb tree
9281da177e4SLinus Torvalds * @dev: the device whose path is being constructed
9291da177e4SLinus Torvalds * @buf: where to put the string
9301da177e4SLinus Torvalds * @size: how big is "buf"?
9311da177e4SLinus Torvalds *
932626f090cSYacine Belkadi * Return: Length of the string (> 0) or negative if size was too small.
9331da177e4SLinus Torvalds *
934626f090cSYacine Belkadi * Note:
9351da177e4SLinus Torvalds * This identifier is intended to be "stable", reflecting physical paths in
9361da177e4SLinus Torvalds * hardware such as physical bus addresses for host controllers or ports on
9371da177e4SLinus Torvalds * USB hubs. That makes it stay the same until systems are physically
9381da177e4SLinus Torvalds * reconfigured, by re-cabling a tree of USB devices or by moving USB host
9391da177e4SLinus Torvalds * controllers. Adding and removing devices, including virtual root hubs
94025985edcSLucas De Marchi * in host controller driver modules, does not change these path identifiers;
9411da177e4SLinus Torvalds * neither does rebooting or re-enumerating. These are more useful identifiers
9421da177e4SLinus Torvalds * than changeable ("unstable") ones like bus numbers or device addresses.
9431da177e4SLinus Torvalds *
9441da177e4SLinus Torvalds * With a partial exception for devices connected to USB 2.0 root hubs, these
9451da177e4SLinus Torvalds * identifiers are also predictable. So long as the device tree isn't changed,
9461da177e4SLinus Torvalds * plugging any USB device into a given hub port always gives it the same path.
9471da177e4SLinus Torvalds * Because of the use of "companion" controllers, devices connected to ports on
9481da177e4SLinus Torvalds * USB 2.0 root hubs (EHCI host controllers) will get one path ID if they are
9491da177e4SLinus Torvalds * high speed, and a different one if they are full or low speed.
9501da177e4SLinus Torvalds */
usb_make_path(struct usb_device * dev,char * buf,size_t size)951969ab2eeSGreg Kroah-Hartman static inline int usb_make_path(struct usb_device *dev, char *buf, size_t size)
9521da177e4SLinus Torvalds {
9531da177e4SLinus Torvalds int actual;
954b724ae77SAlan Stern actual = snprintf(buf, size, "usb-%s-%s", dev->bus->bus_name,
955b724ae77SAlan Stern dev->devpath);
9561da177e4SLinus Torvalds return (actual >= (int)size) ? -1 : actual;
9571da177e4SLinus Torvalds }
9581da177e4SLinus Torvalds
9591da177e4SLinus Torvalds /*-------------------------------------------------------------------------*/
9601da177e4SLinus Torvalds
961b724ae77SAlan Stern #define USB_DEVICE_ID_MATCH_DEVICE \
962b724ae77SAlan Stern (USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
963b724ae77SAlan Stern #define USB_DEVICE_ID_MATCH_DEV_RANGE \
964b724ae77SAlan Stern (USB_DEVICE_ID_MATCH_DEV_LO | USB_DEVICE_ID_MATCH_DEV_HI)
965b724ae77SAlan Stern #define USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION \
966b724ae77SAlan Stern (USB_DEVICE_ID_MATCH_DEVICE | USB_DEVICE_ID_MATCH_DEV_RANGE)
9671da177e4SLinus Torvalds #define USB_DEVICE_ID_MATCH_DEV_INFO \
968b724ae77SAlan Stern (USB_DEVICE_ID_MATCH_DEV_CLASS | \
969b724ae77SAlan Stern USB_DEVICE_ID_MATCH_DEV_SUBCLASS | \
970b724ae77SAlan Stern USB_DEVICE_ID_MATCH_DEV_PROTOCOL)
9711da177e4SLinus Torvalds #define USB_DEVICE_ID_MATCH_INT_INFO \
972b724ae77SAlan Stern (USB_DEVICE_ID_MATCH_INT_CLASS | \
973b724ae77SAlan Stern USB_DEVICE_ID_MATCH_INT_SUBCLASS | \
974b724ae77SAlan Stern USB_DEVICE_ID_MATCH_INT_PROTOCOL)
9751da177e4SLinus Torvalds
9761da177e4SLinus Torvalds /**
9771da177e4SLinus Torvalds * USB_DEVICE - macro used to describe a specific usb device
9781da177e4SLinus Torvalds * @vend: the 16 bit USB Vendor ID
9791da177e4SLinus Torvalds * @prod: the 16 bit USB Product ID
9801da177e4SLinus Torvalds *
9811da177e4SLinus Torvalds * This macro is used to create a struct usb_device_id that matches a
9821da177e4SLinus Torvalds * specific device.
9831da177e4SLinus Torvalds */
9841da177e4SLinus Torvalds #define USB_DEVICE(vend, prod) \
985969ab2eeSGreg Kroah-Hartman .match_flags = USB_DEVICE_ID_MATCH_DEVICE, \
986969ab2eeSGreg Kroah-Hartman .idVendor = (vend), \
987b724ae77SAlan Stern .idProduct = (prod)
9881da177e4SLinus Torvalds /**
989d0bcabcdSRandy Dunlap * USB_DEVICE_VER - describe a specific usb device with a version range
9901da177e4SLinus Torvalds * @vend: the 16 bit USB Vendor ID
9911da177e4SLinus Torvalds * @prod: the 16 bit USB Product ID
9921da177e4SLinus Torvalds * @lo: the bcdDevice_lo value
9931da177e4SLinus Torvalds * @hi: the bcdDevice_hi value
9941da177e4SLinus Torvalds *
9951da177e4SLinus Torvalds * This macro is used to create a struct usb_device_id that matches a
9961da177e4SLinus Torvalds * specific device, with a version range.
9971da177e4SLinus Torvalds */
9981da177e4SLinus Torvalds #define USB_DEVICE_VER(vend, prod, lo, hi) \
999b724ae77SAlan Stern .match_flags = USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION, \
1000969ab2eeSGreg Kroah-Hartman .idVendor = (vend), \
1001969ab2eeSGreg Kroah-Hartman .idProduct = (prod), \
1002969ab2eeSGreg Kroah-Hartman .bcdDevice_lo = (lo), \
1003969ab2eeSGreg Kroah-Hartman .bcdDevice_hi = (hi)
10041da177e4SLinus Torvalds
10051da177e4SLinus Torvalds /**
100617b72febSBjørn Mork * USB_DEVICE_INTERFACE_CLASS - describe a usb device with a specific interface class
100717b72febSBjørn Mork * @vend: the 16 bit USB Vendor ID
100817b72febSBjørn Mork * @prod: the 16 bit USB Product ID
100917b72febSBjørn Mork * @cl: bInterfaceClass value
101017b72febSBjørn Mork *
101117b72febSBjørn Mork * This macro is used to create a struct usb_device_id that matches a
101217b72febSBjørn Mork * specific interface class of devices.
101317b72febSBjørn Mork */
101417b72febSBjørn Mork #define USB_DEVICE_INTERFACE_CLASS(vend, prod, cl) \
101517b72febSBjørn Mork .match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
101617b72febSBjørn Mork USB_DEVICE_ID_MATCH_INT_CLASS, \
101717b72febSBjørn Mork .idVendor = (vend), \
101817b72febSBjørn Mork .idProduct = (prod), \
101917b72febSBjørn Mork .bInterfaceClass = (cl)
102017b72febSBjørn Mork
102117b72febSBjørn Mork /**
1022d0bcabcdSRandy Dunlap * USB_DEVICE_INTERFACE_PROTOCOL - describe a usb device with a specific interface protocol
1023f836ac80SJan Kratochvil * @vend: the 16 bit USB Vendor ID
1024f836ac80SJan Kratochvil * @prod: the 16 bit USB Product ID
1025f836ac80SJan Kratochvil * @pr: bInterfaceProtocol value
1026f836ac80SJan Kratochvil *
1027f836ac80SJan Kratochvil * This macro is used to create a struct usb_device_id that matches a
1028f836ac80SJan Kratochvil * specific interface protocol of devices.
1029f836ac80SJan Kratochvil */
1030f836ac80SJan Kratochvil #define USB_DEVICE_INTERFACE_PROTOCOL(vend, prod, pr) \
1031969ab2eeSGreg Kroah-Hartman .match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
1032969ab2eeSGreg Kroah-Hartman USB_DEVICE_ID_MATCH_INT_PROTOCOL, \
1033f836ac80SJan Kratochvil .idVendor = (vend), \
1034f836ac80SJan Kratochvil .idProduct = (prod), \
1035f836ac80SJan Kratochvil .bInterfaceProtocol = (pr)
1036f836ac80SJan Kratochvil
1037f836ac80SJan Kratochvil /**
103881df2d59SBjørn Mork * USB_DEVICE_INTERFACE_NUMBER - describe a usb device with a specific interface number
103981df2d59SBjørn Mork * @vend: the 16 bit USB Vendor ID
104081df2d59SBjørn Mork * @prod: the 16 bit USB Product ID
104181df2d59SBjørn Mork * @num: bInterfaceNumber value
104281df2d59SBjørn Mork *
104381df2d59SBjørn Mork * This macro is used to create a struct usb_device_id that matches a
104481df2d59SBjørn Mork * specific interface number of devices.
104581df2d59SBjørn Mork */
104681df2d59SBjørn Mork #define USB_DEVICE_INTERFACE_NUMBER(vend, prod, num) \
104781df2d59SBjørn Mork .match_flags = USB_DEVICE_ID_MATCH_DEVICE | \
104881df2d59SBjørn Mork USB_DEVICE_ID_MATCH_INT_NUMBER, \
104981df2d59SBjørn Mork .idVendor = (vend), \
105081df2d59SBjørn Mork .idProduct = (prod), \
105181df2d59SBjørn Mork .bInterfaceNumber = (num)
105281df2d59SBjørn Mork
105381df2d59SBjørn Mork /**
10541da177e4SLinus Torvalds * USB_DEVICE_INFO - macro used to describe a class of usb devices
10551da177e4SLinus Torvalds * @cl: bDeviceClass value
10561da177e4SLinus Torvalds * @sc: bDeviceSubClass value
10571da177e4SLinus Torvalds * @pr: bDeviceProtocol value
10581da177e4SLinus Torvalds *
10591da177e4SLinus Torvalds * This macro is used to create a struct usb_device_id that matches a
10601da177e4SLinus Torvalds * specific class of devices.
10611da177e4SLinus Torvalds */
10621da177e4SLinus Torvalds #define USB_DEVICE_INFO(cl, sc, pr) \
1063969ab2eeSGreg Kroah-Hartman .match_flags = USB_DEVICE_ID_MATCH_DEV_INFO, \
1064969ab2eeSGreg Kroah-Hartman .bDeviceClass = (cl), \
1065969ab2eeSGreg Kroah-Hartman .bDeviceSubClass = (sc), \
1066969ab2eeSGreg Kroah-Hartman .bDeviceProtocol = (pr)
10671da177e4SLinus Torvalds
10681da177e4SLinus Torvalds /**
10691da177e4SLinus Torvalds * USB_INTERFACE_INFO - macro used to describe a class of usb interfaces
10701da177e4SLinus Torvalds * @cl: bInterfaceClass value
10711da177e4SLinus Torvalds * @sc: bInterfaceSubClass value
10721da177e4SLinus Torvalds * @pr: bInterfaceProtocol value
10731da177e4SLinus Torvalds *
10741da177e4SLinus Torvalds * This macro is used to create a struct usb_device_id that matches a
10751da177e4SLinus Torvalds * specific class of interfaces.
10761da177e4SLinus Torvalds */
10771da177e4SLinus Torvalds #define USB_INTERFACE_INFO(cl, sc, pr) \
1078969ab2eeSGreg Kroah-Hartman .match_flags = USB_DEVICE_ID_MATCH_INT_INFO, \
1079969ab2eeSGreg Kroah-Hartman .bInterfaceClass = (cl), \
1080969ab2eeSGreg Kroah-Hartman .bInterfaceSubClass = (sc), \
1081969ab2eeSGreg Kroah-Hartman .bInterfaceProtocol = (pr)
10821da177e4SLinus Torvalds
10838538f96aSDaniel Drake /**
1084d0bcabcdSRandy Dunlap * USB_DEVICE_AND_INTERFACE_INFO - describe a specific usb device with a class of usb interfaces
10858538f96aSDaniel Drake * @vend: the 16 bit USB Vendor ID
10868538f96aSDaniel Drake * @prod: the 16 bit USB Product ID
10878538f96aSDaniel Drake * @cl: bInterfaceClass value
10888538f96aSDaniel Drake * @sc: bInterfaceSubClass value
10898538f96aSDaniel Drake * @pr: bInterfaceProtocol value
10908538f96aSDaniel Drake *
10918538f96aSDaniel Drake * This macro is used to create a struct usb_device_id that matches a
10928538f96aSDaniel Drake * specific device with a specific class of interfaces.
10938538f96aSDaniel Drake *
10948538f96aSDaniel Drake * This is especially useful when explicitly matching devices that have
10958538f96aSDaniel Drake * vendor specific bDeviceClass values, but standards-compliant interfaces.
10968538f96aSDaniel Drake */
10978538f96aSDaniel Drake #define USB_DEVICE_AND_INTERFACE_INFO(vend, prod, cl, sc, pr) \
10988538f96aSDaniel Drake .match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
10998538f96aSDaniel Drake | USB_DEVICE_ID_MATCH_DEVICE, \
1100969ab2eeSGreg Kroah-Hartman .idVendor = (vend), \
1101969ab2eeSGreg Kroah-Hartman .idProduct = (prod), \
11028538f96aSDaniel Drake .bInterfaceClass = (cl), \
1103969ab2eeSGreg Kroah-Hartman .bInterfaceSubClass = (sc), \
1104969ab2eeSGreg Kroah-Hartman .bInterfaceProtocol = (pr)
11058538f96aSDaniel Drake
1106d81a5d19SGustavo Padovan /**
1107d81a5d19SGustavo Padovan * USB_VENDOR_AND_INTERFACE_INFO - describe a specific usb vendor with a class of usb interfaces
1108d81a5d19SGustavo Padovan * @vend: the 16 bit USB Vendor ID
1109d81a5d19SGustavo Padovan * @cl: bInterfaceClass value
1110d81a5d19SGustavo Padovan * @sc: bInterfaceSubClass value
1111d81a5d19SGustavo Padovan * @pr: bInterfaceProtocol value
1112d81a5d19SGustavo Padovan *
1113d81a5d19SGustavo Padovan * This macro is used to create a struct usb_device_id that matches a
1114d81a5d19SGustavo Padovan * specific vendor with a specific class of interfaces.
1115d81a5d19SGustavo Padovan *
1116d81a5d19SGustavo Padovan * This is especially useful when explicitly matching devices that have
1117d81a5d19SGustavo Padovan * vendor specific bDeviceClass values, but standards-compliant interfaces.
1118d81a5d19SGustavo Padovan */
1119d81a5d19SGustavo Padovan #define USB_VENDOR_AND_INTERFACE_INFO(vend, cl, sc, pr) \
1120d81a5d19SGustavo Padovan .match_flags = USB_DEVICE_ID_MATCH_INT_INFO \
1121d81a5d19SGustavo Padovan | USB_DEVICE_ID_MATCH_VENDOR, \
1122d81a5d19SGustavo Padovan .idVendor = (vend), \
1123d81a5d19SGustavo Padovan .bInterfaceClass = (cl), \
1124d81a5d19SGustavo Padovan .bInterfaceSubClass = (sc), \
1125d81a5d19SGustavo Padovan .bInterfaceProtocol = (pr)
1126d81a5d19SGustavo Padovan
1127b724ae77SAlan Stern /* ----------------------------------------------------------------------- */
11281da177e4SLinus Torvalds
112993bacefcSGreg Kroah-Hartman /* Stuff for dynamic usb ids */
1130733260ffSGreg Kroah-Hartman struct usb_dynids {
1131733260ffSGreg Kroah-Hartman spinlock_t lock;
1132733260ffSGreg Kroah-Hartman struct list_head list;
1133733260ffSGreg Kroah-Hartman };
1134733260ffSGreg Kroah-Hartman
113593bacefcSGreg Kroah-Hartman struct usb_dynid {
113693bacefcSGreg Kroah-Hartman struct list_head node;
113793bacefcSGreg Kroah-Hartman struct usb_device_id id;
113893bacefcSGreg Kroah-Hartman };
113993bacefcSGreg Kroah-Hartman
114093bacefcSGreg Kroah-Hartman extern ssize_t usb_store_new_id(struct usb_dynids *dynids,
11412fc82c2dSWolfram Sang const struct usb_device_id *id_table,
114293bacefcSGreg Kroah-Hartman struct device_driver *driver,
114393bacefcSGreg Kroah-Hartman const char *buf, size_t count);
114493bacefcSGreg Kroah-Hartman
1145ef206f3fSBjørn Mork extern ssize_t usb_show_dynids(struct usb_dynids *dynids, char *buf);
1146ef206f3fSBjørn Mork
11471da177e4SLinus Torvalds /**
11488bb54ab5SAlan Stern * struct usbdrv_wrap - wrapper for driver-model structure
11498bb54ab5SAlan Stern * @driver: The driver-model core driver structure.
11508bb54ab5SAlan Stern * @for_devices: Non-zero for device drivers, 0 for interface drivers.
11518bb54ab5SAlan Stern */
11528bb54ab5SAlan Stern struct usbdrv_wrap {
11538bb54ab5SAlan Stern struct device_driver driver;
11548bb54ab5SAlan Stern int for_devices;
11558bb54ab5SAlan Stern };
11568bb54ab5SAlan Stern
11578bb54ab5SAlan Stern /**
11588bb54ab5SAlan Stern * struct usb_driver - identifies USB interface driver to usbcore
11591da177e4SLinus Torvalds * @name: The driver name should be unique among USB drivers,
11601da177e4SLinus Torvalds * and should normally be the same as the module name.
11611da177e4SLinus Torvalds * @probe: Called to see if the driver is willing to manage a particular
11621da177e4SLinus Torvalds * interface on a device. If it is, probe returns zero and uses
11637ef4f060SOliver Neukum * usb_set_intfdata() to associate driver-specific data with the
11641da177e4SLinus Torvalds * interface. It may also use usb_set_interface() to specify the
11651da177e4SLinus Torvalds * appropriate altsetting. If unwilling to manage the interface,
116625985edcSLucas De Marchi * return -ENODEV, if genuine IO errors occurred, an appropriate
11677ef4f060SOliver Neukum * negative errno value.
11681da177e4SLinus Torvalds * @disconnect: Called when the interface is no longer accessible, usually
11691da177e4SLinus Torvalds * because its device has been (or is being) disconnected or the
11701da177e4SLinus Torvalds * driver module is being unloaded.
1171a91be2acSRandy Dunlap * @unlocked_ioctl: Used for drivers that want to talk to userspace through
11721da177e4SLinus Torvalds * the "usbfs" filesystem. This lets devices provide ways to
11731da177e4SLinus Torvalds * expose information to user space regardless of where they
11741da177e4SLinus Torvalds * do (or don't) show up otherwise in the filesystem.
1175303f0847SMing Lei * @suspend: Called when the device is going to be suspended by the
1176303f0847SMing Lei * system either from system sleep or runtime suspend context. The
1177303f0847SMing Lei * return value will be ignored in system sleep context, so do NOT
1178303f0847SMing Lei * try to continue using the device if suspend fails in this case.
1179303f0847SMing Lei * Instead, let the resume or reset-resume routine recover from
1180303f0847SMing Lei * the failure.
11811da177e4SLinus Torvalds * @resume: Called when the device is being resumed by the system.
1182f07600cfSAlan Stern * @reset_resume: Called when the suspended device has been reset instead
1183f07600cfSAlan Stern * of being resumed.
11846498d9dbSAlan Stern * @pre_reset: Called by usb_reset_device() when the device is about to be
11856498d9dbSAlan Stern * reset. This routine must not return until the driver has no active
11866498d9dbSAlan Stern * URBs for the device, and no more URBs may be submitted until the
11876498d9dbSAlan Stern * post_reset method is called.
1188742120c6SMing Lei * @post_reset: Called by usb_reset_device() after the device
11897ef4f060SOliver Neukum * has been reset
11901da177e4SLinus Torvalds * @id_table: USB drivers use ID table to support hotplugging.
11911da177e4SLinus Torvalds * Export this with MODULE_DEVICE_TABLE(usb,...). This must be set
11921da177e4SLinus Torvalds * or your driver's probe function will never get called.
1193b71b283eSGreg Kroah-Hartman * @dev_groups: Attributes attached to the device that will be created once it
1194b71b283eSGreg Kroah-Hartman * is bound to the driver.
1195733260ffSGreg Kroah-Hartman * @dynids: used internally to hold the list of dynamically added device
1196733260ffSGreg Kroah-Hartman * ids for this driver.
11978bb54ab5SAlan Stern * @drvwrap: Driver-model core structure wrapper.
1198ba9dc657SGreg Kroah-Hartman * @no_dynamic_id: if set to 1, the USB core will not allow dynamic ids to be
1199ba9dc657SGreg Kroah-Hartman * added to this driver by preventing the sysfs file from being created.
1200645daaabSAlan Stern * @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
1201645daaabSAlan Stern * for interfaces bound to this driver.
12029da82bd4SAlan Stern * @soft_unbind: if set to 1, the USB core will not kill URBs and disable
12039da82bd4SAlan Stern * endpoints before calling the driver's disconnect method.
12046fb650d4SAlan Stern * @disable_hub_initiated_lpm: if set to 1, the USB core will not allow hubs
12058afa408cSSarah Sharp * to initiate lower power link state transitions when an idle timeout
12068afa408cSSarah Sharp * occurs. Device-initiated USB 3.0 link PM will still be allowed.
12071da177e4SLinus Torvalds *
12088bb54ab5SAlan Stern * USB interface drivers must provide a name, probe() and disconnect()
12098bb54ab5SAlan Stern * methods, and an id_table. Other driver fields are optional.
12101da177e4SLinus Torvalds *
12111da177e4SLinus Torvalds * The id_table is used in hotplugging. It holds a set of descriptors,
12121da177e4SLinus Torvalds * and specialized data may be associated with each entry. That table
12131da177e4SLinus Torvalds * is used by both user and kernel mode hotplugging support.
12141da177e4SLinus Torvalds *
12151da177e4SLinus Torvalds * The probe() and disconnect() methods are called in a context where
12161da177e4SLinus Torvalds * they can sleep, but they should avoid abusing the privilege. Most
12171da177e4SLinus Torvalds * work to connect to a device should be done when the device is opened,
12181da177e4SLinus Torvalds * and undone at the last close. The disconnect code needs to address
12191da177e4SLinus Torvalds * concurrency issues with respect to open() and close() methods, as
12201da177e4SLinus Torvalds * well as forcing all pending I/O requests to complete (by unlinking
12211da177e4SLinus Torvalds * them as necessary, and blocking until the unlinks complete).
12221da177e4SLinus Torvalds */
12231da177e4SLinus Torvalds struct usb_driver {
12241da177e4SLinus Torvalds const char *name;
12251da177e4SLinus Torvalds
12261da177e4SLinus Torvalds int (*probe) (struct usb_interface *intf,
12271da177e4SLinus Torvalds const struct usb_device_id *id);
12281da177e4SLinus Torvalds
12291da177e4SLinus Torvalds void (*disconnect) (struct usb_interface *intf);
12301da177e4SLinus Torvalds
1231c532b29aSAndi Kleen int (*unlocked_ioctl) (struct usb_interface *intf, unsigned int code,
1232b724ae77SAlan Stern void *buf);
12331da177e4SLinus Torvalds
123427d72e85SDavid Brownell int (*suspend) (struct usb_interface *intf, pm_message_t message);
12351da177e4SLinus Torvalds int (*resume) (struct usb_interface *intf);
1236f07600cfSAlan Stern int (*reset_resume)(struct usb_interface *intf);
12371da177e4SLinus Torvalds
1238f07600cfSAlan Stern int (*pre_reset)(struct usb_interface *intf);
1239f07600cfSAlan Stern int (*post_reset)(struct usb_interface *intf);
124079efa097SAlan Stern
12411da177e4SLinus Torvalds const struct usb_device_id *id_table;
1242b71b283eSGreg Kroah-Hartman const struct attribute_group **dev_groups;
12431da177e4SLinus Torvalds
1244733260ffSGreg Kroah-Hartman struct usb_dynids dynids;
12458bb54ab5SAlan Stern struct usbdrv_wrap drvwrap;
1246ba9dc657SGreg Kroah-Hartman unsigned int no_dynamic_id:1;
1247645daaabSAlan Stern unsigned int supports_autosuspend:1;
12488afa408cSSarah Sharp unsigned int disable_hub_initiated_lpm:1;
12499da82bd4SAlan Stern unsigned int soft_unbind:1;
12501da177e4SLinus Torvalds };
12518bb54ab5SAlan Stern #define to_usb_driver(d) container_of(d, struct usb_driver, drvwrap.driver)
12528bb54ab5SAlan Stern
12538bb54ab5SAlan Stern /**
12548bb54ab5SAlan Stern * struct usb_device_driver - identifies USB device driver to usbcore
12558bb54ab5SAlan Stern * @name: The driver name should be unique among USB drivers,
12568bb54ab5SAlan Stern * and should normally be the same as the module name.
125743ff9869SRandy Dunlap * @match: If set, used for better device/driver matching.
12588bb54ab5SAlan Stern * @probe: Called to see if the driver is willing to manage a particular
12598bb54ab5SAlan Stern * device. If it is, probe returns zero and uses dev_set_drvdata()
12608bb54ab5SAlan Stern * to associate driver-specific data with the device. If unwilling
12618bb54ab5SAlan Stern * to manage the device, return a negative errno value.
12628bb54ab5SAlan Stern * @disconnect: Called when the device is no longer accessible, usually
12638bb54ab5SAlan Stern * because it has been (or is being) disconnected or the driver's
12648bb54ab5SAlan Stern * module is being unloaded.
12658bb54ab5SAlan Stern * @suspend: Called when the device is going to be suspended by the system.
12668bb54ab5SAlan Stern * @resume: Called when the device is being resumed by the system.
12677d9c1d2fSGreg Kroah-Hartman * @dev_groups: Attributes attached to the device that will be created once it
12687d9c1d2fSGreg Kroah-Hartman * is bound to the driver.
12698bb54ab5SAlan Stern * @drvwrap: Driver-model core structure wrapper.
127043ff9869SRandy Dunlap * @id_table: used with @match() to select better matching driver at
127143ff9869SRandy Dunlap * probe() time.
1272645daaabSAlan Stern * @supports_autosuspend: if set to 0, the USB core will not allow autosuspend
1273645daaabSAlan Stern * for devices bound to this driver.
1274c9d50337SBastien Nocera * @generic_subclass: if set to 1, the generic USB driver's probe, disconnect,
1275c9d50337SBastien Nocera * resume and suspend functions will be called in addition to the driver's
1276c9d50337SBastien Nocera * own, so this part of the setup does not need to be replicated.
12778bb54ab5SAlan Stern *
127843ff9869SRandy Dunlap * USB drivers must provide all the fields listed above except drvwrap,
127943ff9869SRandy Dunlap * match, and id_table.
12808bb54ab5SAlan Stern */
12818bb54ab5SAlan Stern struct usb_device_driver {
12828bb54ab5SAlan Stern const char *name;
12838bb54ab5SAlan Stern
128488b7381aSBastien Nocera bool (*match) (struct usb_device *udev);
12858bb54ab5SAlan Stern int (*probe) (struct usb_device *udev);
12868bb54ab5SAlan Stern void (*disconnect) (struct usb_device *udev);
12878bb54ab5SAlan Stern
12888bb54ab5SAlan Stern int (*suspend) (struct usb_device *udev, pm_message_t message);
128965bfd296SAlan Stern int (*resume) (struct usb_device *udev, pm_message_t message);
12907d9c1d2fSGreg Kroah-Hartman const struct attribute_group **dev_groups;
12918bb54ab5SAlan Stern struct usbdrv_wrap drvwrap;
129288b7381aSBastien Nocera const struct usb_device_id *id_table;
1293645daaabSAlan Stern unsigned int supports_autosuspend:1;
1294c9d50337SBastien Nocera unsigned int generic_subclass:1;
12958bb54ab5SAlan Stern };
12968bb54ab5SAlan Stern #define to_usb_device_driver(d) container_of(d, struct usb_device_driver, \
12978bb54ab5SAlan Stern drvwrap.driver)
12981da177e4SLinus Torvalds
12991da177e4SLinus Torvalds /**
13001da177e4SLinus Torvalds * struct usb_class_driver - identifies a USB driver that wants to use the USB major number
1301d6e5bcf4SGreg Kroah-Hartman * @name: the usb class device name for this driver. Will show up in sysfs.
1302e454cea2SKay Sievers * @devnode: Callback to provide a naming hint for a possible
1303e376bbbbSRandy Dunlap * device node to create.
13041da177e4SLinus Torvalds * @fops: pointer to the struct file_operations of this driver.
13051da177e4SLinus Torvalds * @minor_base: the start of the minor range for this driver.
13061da177e4SLinus Torvalds *
13071da177e4SLinus Torvalds * This structure is used for the usb_register_dev() and
1308864e2fe9SAmitesh Singh * usb_deregister_dev() functions, to consolidate a number of the
13091da177e4SLinus Torvalds * parameters used for them.
13101da177e4SLinus Torvalds */
13111da177e4SLinus Torvalds struct usb_class_driver {
13121da177e4SLinus Torvalds char *name;
13135033ac5cSGreg Kroah-Hartman char *(*devnode)(const struct device *dev, umode_t *mode);
131499ac48f5SArjan van de Ven const struct file_operations *fops;
13151da177e4SLinus Torvalds int minor_base;
13161da177e4SLinus Torvalds };
13171da177e4SLinus Torvalds
13181da177e4SLinus Torvalds /*
13191da177e4SLinus Torvalds * use these in module_init()/module_exit()
13201da177e4SLinus Torvalds * and don't forget MODULE_DEVICE_TABLE(usb, ...)
13211da177e4SLinus Torvalds */
132280f745fbSGreg Kroah-Hartman extern int usb_register_driver(struct usb_driver *, struct module *,
132380f745fbSGreg Kroah-Hartman const char *);
1324eb5589a8SPaul Gortmaker
1325eb5589a8SPaul Gortmaker /* use a define to avoid include chaining to get THIS_MODULE & friends */
1326eb5589a8SPaul Gortmaker #define usb_register(driver) \
1327eb5589a8SPaul Gortmaker usb_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)
1328eb5589a8SPaul Gortmaker
13291da177e4SLinus Torvalds extern void usb_deregister(struct usb_driver *);
13301da177e4SLinus Torvalds
1331f3a6a4b6SGreg Kroah-Hartman /**
1332f3a6a4b6SGreg Kroah-Hartman * module_usb_driver() - Helper macro for registering a USB driver
1333f3a6a4b6SGreg Kroah-Hartman * @__usb_driver: usb_driver struct
1334f3a6a4b6SGreg Kroah-Hartman *
1335f3a6a4b6SGreg Kroah-Hartman * Helper macro for USB drivers which do not do anything special in module
1336f3a6a4b6SGreg Kroah-Hartman * init/exit. This eliminates a lot of boilerplate. Each module may only
1337f3a6a4b6SGreg Kroah-Hartman * use this macro once, and calling it replaces module_init() and module_exit()
1338f3a6a4b6SGreg Kroah-Hartman */
1339f3a6a4b6SGreg Kroah-Hartman #define module_usb_driver(__usb_driver) \
1340f3a6a4b6SGreg Kroah-Hartman module_driver(__usb_driver, usb_register, \
1341f3a6a4b6SGreg Kroah-Hartman usb_deregister)
1342f3a6a4b6SGreg Kroah-Hartman
13438bb54ab5SAlan Stern extern int usb_register_device_driver(struct usb_device_driver *,
13448bb54ab5SAlan Stern struct module *);
13458bb54ab5SAlan Stern extern void usb_deregister_device_driver(struct usb_device_driver *);
13468bb54ab5SAlan Stern
13471da177e4SLinus Torvalds extern int usb_register_dev(struct usb_interface *intf,
13481da177e4SLinus Torvalds struct usb_class_driver *class_driver);
13491da177e4SLinus Torvalds extern void usb_deregister_dev(struct usb_interface *intf,
13501da177e4SLinus Torvalds struct usb_class_driver *class_driver);
13511da177e4SLinus Torvalds
13521da177e4SLinus Torvalds extern int usb_disabled(void);
13531da177e4SLinus Torvalds
1354b724ae77SAlan Stern /* ----------------------------------------------------------------------- */
13551da177e4SLinus Torvalds
13561da177e4SLinus Torvalds /*
13571da177e4SLinus Torvalds * URB support, for asynchronous request completions
13581da177e4SLinus Torvalds */
13591da177e4SLinus Torvalds
13601da177e4SLinus Torvalds /*
13611da177e4SLinus Torvalds * urb->transfer_flags:
1362fea34091SAlan Stern *
1363fea34091SAlan Stern * Note: URB_DIR_IN/OUT is automatically set in usb_submit_urb().
13641da177e4SLinus Torvalds */
13651da177e4SLinus Torvalds #define URB_SHORT_NOT_OK 0x0001 /* report short reads as errors */
1366a03bede5SAlan Stern #define URB_ISO_ASAP 0x0002 /* iso-only; use the first unexpired
1367a03bede5SAlan Stern * slot in the schedule */
13681da177e4SLinus Torvalds #define URB_NO_TRANSFER_DMA_MAP 0x0004 /* urb->transfer_dma valid on submit */
1369b724ae77SAlan Stern #define URB_ZERO_PACKET 0x0040 /* Finish bulk OUT with short packet */
1370b724ae77SAlan Stern #define URB_NO_INTERRUPT 0x0080 /* HINT: no non-error interrupt
1371b724ae77SAlan Stern * needed */
13728b3b01c8SMarcel Holtmann #define URB_FREE_BUFFER 0x0100 /* Free transfer buffer with the URB */
13731da177e4SLinus Torvalds
1374ff9c895fSAlan Stern /* The following flags are used internally by usbcore and HCDs */
1375fea34091SAlan Stern #define URB_DIR_IN 0x0200 /* Transfer from device to host */
1376fea34091SAlan Stern #define URB_DIR_OUT 0
1377fea34091SAlan Stern #define URB_DIR_MASK URB_DIR_IN
1378fea34091SAlan Stern
1379ff9c895fSAlan Stern #define URB_DMA_MAP_SINGLE 0x00010000 /* Non-scatter-gather mapping */
1380ff9c895fSAlan Stern #define URB_DMA_MAP_PAGE 0x00020000 /* HCD-unsupported S-G */
1381ff9c895fSAlan Stern #define URB_DMA_MAP_SG 0x00040000 /* HCD-supported S-G */
1382ff9c895fSAlan Stern #define URB_MAP_LOCAL 0x00080000 /* HCD-local-memory mapping */
1383ff9c895fSAlan Stern #define URB_SETUP_MAP_SINGLE 0x00100000 /* Setup packet DMA mapped */
1384ff9c895fSAlan Stern #define URB_SETUP_MAP_LOCAL 0x00200000 /* HCD-local setup packet */
1385ff9c895fSAlan Stern #define URB_DMA_SG_COMBINED 0x00400000 /* S-G entries were combined */
13862694a48dSRobert Morell #define URB_ALIGNED_TEMP_BUFFER 0x00800000 /* Temp buffer was alloc'd */
1387ff9c895fSAlan Stern
13881da177e4SLinus Torvalds struct usb_iso_packet_descriptor {
13891da177e4SLinus Torvalds unsigned int offset;
13901da177e4SLinus Torvalds unsigned int length; /* expected length */
13911da177e4SLinus Torvalds unsigned int actual_length;
1392d1bbb600SPete Zaitcev int status;
13931da177e4SLinus Torvalds };
13941da177e4SLinus Torvalds
13951da177e4SLinus Torvalds struct urb;
13961da177e4SLinus Torvalds
139751a2f077SOliver Neukum struct usb_anchor {
139851a2f077SOliver Neukum struct list_head urb_list;
139951a2f077SOliver Neukum wait_queue_head_t wait;
140051a2f077SOliver Neukum spinlock_t lock;
14016ec4147eSHans de Goede atomic_t suspend_wakeups;
14026a2839beSOliver Neukum unsigned int poisoned:1;
140351a2f077SOliver Neukum };
140451a2f077SOliver Neukum
init_usb_anchor(struct usb_anchor * anchor)140551a2f077SOliver Neukum static inline void init_usb_anchor(struct usb_anchor *anchor)
140651a2f077SOliver Neukum {
14079ef73dbdSHans de Goede memset(anchor, 0, sizeof(*anchor));
140851a2f077SOliver Neukum INIT_LIST_HEAD(&anchor->urb_list);
140951a2f077SOliver Neukum init_waitqueue_head(&anchor->wait);
141051a2f077SOliver Neukum spin_lock_init(&anchor->lock);
141151a2f077SOliver Neukum }
141251a2f077SOliver Neukum
14137d12e780SDavid Howells typedef void (*usb_complete_t)(struct urb *);
14141da177e4SLinus Torvalds
14151da177e4SLinus Torvalds /**
14161da177e4SLinus Torvalds * struct urb - USB Request Block
14171da177e4SLinus Torvalds * @urb_list: For use by current owner of the URB.
141851a2f077SOliver Neukum * @anchor_list: membership in the list of an anchor
141951a2f077SOliver Neukum * @anchor: to anchor URBs to a common mooring
14205b653c79SAlan Stern * @ep: Points to the endpoint's data structure. Will eventually
14215b653c79SAlan Stern * replace @pipe.
14221da177e4SLinus Torvalds * @pipe: Holds endpoint number, direction, type, and more.
14231da177e4SLinus Torvalds * Create these values with the eight macros available;
14241da177e4SLinus Torvalds * usb_{snd,rcv}TYPEpipe(dev,endpoint), where the TYPE is "ctrl"
14251da177e4SLinus Torvalds * (control), "bulk", "int" (interrupt), or "iso" (isochronous).
14261da177e4SLinus Torvalds * For example usb_sndbulkpipe() or usb_rcvintpipe(). Endpoint
14271da177e4SLinus Torvalds * numbers range from zero to fifteen. Note that "in" endpoint two
14281da177e4SLinus Torvalds * is a different endpoint (and pipe) from "out" endpoint two.
14291da177e4SLinus Torvalds * The current configuration controls the existence, type, and
14301da177e4SLinus Torvalds * maximum packet size of any given endpoint.
1431c6ba1c2aSRandy Dunlap * @stream_id: the endpoint's stream ID for bulk streams
14321da177e4SLinus Torvalds * @dev: Identifies the USB device to perform the request.
14331da177e4SLinus Torvalds * @status: This is read in non-iso completion functions to get the
14341da177e4SLinus Torvalds * status of the particular request. ISO requests only use it
14351da177e4SLinus Torvalds * to tell whether the URB was unlinked; detailed status for
14361da177e4SLinus Torvalds * each frame is in the fields of the iso_frame-desc.
14371da177e4SLinus Torvalds * @transfer_flags: A variety of flags may be used to affect how URB
14381da177e4SLinus Torvalds * submission, unlinking, or operation are handled. Different
14391da177e4SLinus Torvalds * kinds of URB can use different flags.
14404e9e9200SPete Zaitcev * @transfer_buffer: This identifies the buffer to (or from) which the I/O
14414e9e9200SPete Zaitcev * request will be performed unless URB_NO_TRANSFER_DMA_MAP is set
14424e9e9200SPete Zaitcev * (however, do not leave garbage in transfer_buffer even then).
14434e9e9200SPete Zaitcev * This buffer must be suitable for DMA; allocate it with
14441da177e4SLinus Torvalds * kmalloc() or equivalent. For transfers to "in" endpoints, contents
14451da177e4SLinus Torvalds * of this buffer will be modified. This buffer is used for the data
14461da177e4SLinus Torvalds * stage of control transfers.
14471da177e4SLinus Torvalds * @transfer_dma: When transfer_flags includes URB_NO_TRANSFER_DMA_MAP,
14481da177e4SLinus Torvalds * the device driver is saying that it provided this DMA address,
14491da177e4SLinus Torvalds * which the host controller driver should use in preference to the
14501da177e4SLinus Torvalds * transfer_buffer.
145110e232c5SMing Lei * @sg: scatter gather buffer list, the buffer size of each element in
145210e232c5SMing Lei * the list (except the last) must be divisible by the endpoint's
1453bcc48f1aSMing Lei * max packet size if no_sg_constraint isn't set in 'struct usb_bus'
14544d922612SRandy Dunlap * @num_mapped_sgs: (internal) number of mapped sg entries
1455e376bbbbSRandy Dunlap * @num_sgs: number of entries in the sg list
14561da177e4SLinus Torvalds * @transfer_buffer_length: How big is transfer_buffer. The transfer may
14571da177e4SLinus Torvalds * be broken up into chunks according to the current maximum packet
14581da177e4SLinus Torvalds * size for the endpoint, which is a function of the configuration
14591da177e4SLinus Torvalds * and is encoded in the pipe. When the length is zero, neither
14601da177e4SLinus Torvalds * transfer_buffer nor transfer_dma is used.
14611da177e4SLinus Torvalds * @actual_length: This is read in non-iso completion functions, and
14621da177e4SLinus Torvalds * it tells how many bytes (out of transfer_buffer_length) were
14631da177e4SLinus Torvalds * transferred. It will normally be the same as requested, unless
14641da177e4SLinus Torvalds * either an error was reported or a short read was performed.
14651da177e4SLinus Torvalds * The URB_SHORT_NOT_OK transfer flag may be used to make such
14661da177e4SLinus Torvalds * short reads be reported as errors.
14671da177e4SLinus Torvalds * @setup_packet: Only used for control transfers, this points to eight bytes
14681da177e4SLinus Torvalds * of setup data. Control transfers always start by sending this data
14691da177e4SLinus Torvalds * to the device. Then transfer_buffer is read or written, if needed.
147085bcb5eeSAlan Stern * @setup_dma: DMA pointer for the setup packet. The caller must not use
147185bcb5eeSAlan Stern * this field; setup_packet must point to a valid buffer.
14721da177e4SLinus Torvalds * @start_frame: Returns the initial frame for isochronous transfers.
14731da177e4SLinus Torvalds * @number_of_packets: Lists the number of ISO transfer buffers.
14741da177e4SLinus Torvalds * @interval: Specifies the polling interval for interrupt or isochronous
1475411c9403SAnand Gadiyar * transfers. The units are frames (milliseconds) for full and low
1476f09a15e6SMatthew Wilcox * speed devices, and microframes (1/8 millisecond) for highspeed
1477f09a15e6SMatthew Wilcox * and SuperSpeed devices.
14781da177e4SLinus Torvalds * @error_count: Returns the number of ISO transfers that reported errors.
14791da177e4SLinus Torvalds * @context: For use in completion functions. This normally points to
14801da177e4SLinus Torvalds * request-specific driver context.
14811da177e4SLinus Torvalds * @complete: Completion handler. This URB is passed as the parameter to the
14821da177e4SLinus Torvalds * completion function. The completion function may then do what
14831da177e4SLinus Torvalds * it likes with the URB, including resubmitting or freeing it.
14841da177e4SLinus Torvalds * @iso_frame_desc: Used to provide arrays of ISO transfer buffers and to
14851da177e4SLinus Torvalds * collect the transfer status for each buffer.
14861da177e4SLinus Torvalds *
14871da177e4SLinus Torvalds * This structure identifies USB transfer requests. URBs must be allocated by
14881da177e4SLinus Torvalds * calling usb_alloc_urb() and freed with a call to usb_free_urb().
14891da177e4SLinus Torvalds * Initialization may be done using various usb_fill_*_urb() functions. URBs
14901da177e4SLinus Torvalds * are submitted using usb_submit_urb(), and pending requests may be canceled
14911da177e4SLinus Torvalds * using usb_unlink_urb() or usb_kill_urb().
14921da177e4SLinus Torvalds *
14931da177e4SLinus Torvalds * Data Transfer Buffers:
14941da177e4SLinus Torvalds *
14951da177e4SLinus Torvalds * Normally drivers provide I/O buffers allocated with kmalloc() or otherwise
14961da177e4SLinus Torvalds * taken from the general page pool. That is provided by transfer_buffer
14971da177e4SLinus Torvalds * (control requests also use setup_packet), and host controller drivers
14981da177e4SLinus Torvalds * perform a dma mapping (and unmapping) for each buffer transferred. Those
14991da177e4SLinus Torvalds * mapping operations can be expensive on some platforms (perhaps using a dma
15001da177e4SLinus Torvalds * bounce buffer or talking to an IOMMU),
15011da177e4SLinus Torvalds * although they're cheap on commodity x86 and ppc hardware.
15021da177e4SLinus Torvalds *
150385bcb5eeSAlan Stern * Alternatively, drivers may pass the URB_NO_TRANSFER_DMA_MAP transfer flag,
150485bcb5eeSAlan Stern * which tells the host controller driver that no such mapping is needed for
150585bcb5eeSAlan Stern * the transfer_buffer since
15061da177e4SLinus Torvalds * the device driver is DMA-aware. For example, a device driver might
1507073900a2SDaniel Mack * allocate a DMA buffer with usb_alloc_coherent() or call usb_buffer_map().
150885bcb5eeSAlan Stern * When this transfer flag is provided, host controller drivers will
150985bcb5eeSAlan Stern * attempt to use the dma address found in the transfer_dma
151085bcb5eeSAlan Stern * field rather than determining a dma address themselves.
15114e9e9200SPete Zaitcev *
15124e9e9200SPete Zaitcev * Note that transfer_buffer must still be set if the controller
1513edfbcb32SChristoph Hellwig * does not support DMA (as indicated by hcd_uses_dma()) and when talking
151424bb0076SZhen Lei * to root hub. If you have to transfer between highmem zone and the device
15154e9e9200SPete Zaitcev * on such controller, create a bounce buffer or bail out with an error.
15164e9e9200SPete Zaitcev * If transfer_buffer cannot be set (is in highmem) and the controller is DMA
15174e9e9200SPete Zaitcev * capable, assign NULL to it, so that usbmon knows not to use the value.
15184e9e9200SPete Zaitcev * The setup_packet must always be set, so it cannot be located in highmem.
15191da177e4SLinus Torvalds *
15201da177e4SLinus Torvalds * Initialization:
15211da177e4SLinus Torvalds *
15221da177e4SLinus Torvalds * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
1523b375a049SAlan Stern * zero), and complete fields. All URBs must also initialize
15241da177e4SLinus Torvalds * transfer_buffer and transfer_buffer_length. They may provide the
15251da177e4SLinus Torvalds * URB_SHORT_NOT_OK transfer flag, indicating that short reads are
15261da177e4SLinus Torvalds * to be treated as errors; that flag is invalid for write requests.
15271da177e4SLinus Torvalds *
15281da177e4SLinus Torvalds * Bulk URBs may
15291da177e4SLinus Torvalds * use the URB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers
15301da177e4SLinus Torvalds * should always terminate with a short packet, even if it means adding an
15311da177e4SLinus Torvalds * extra zero length packet.
15321da177e4SLinus Torvalds *
153385bcb5eeSAlan Stern * Control URBs must provide a valid pointer in the setup_packet field.
153485bcb5eeSAlan Stern * Unlike the transfer_buffer, the setup_packet may not be mapped for DMA
153585bcb5eeSAlan Stern * beforehand.
15361da177e4SLinus Torvalds *
15371da177e4SLinus Torvalds * Interrupt URBs must provide an interval, saying how often (in milliseconds
15381da177e4SLinus Torvalds * or, for highspeed devices, 125 microsecond units)
15391da177e4SLinus Torvalds * to poll for transfers. After the URB has been submitted, the interval
15401da177e4SLinus Torvalds * field reflects how the transfer was actually scheduled.
15411da177e4SLinus Torvalds * The polling interval may be more frequent than requested.
15421da177e4SLinus Torvalds * For example, some controllers have a maximum interval of 32 milliseconds,
15431da177e4SLinus Torvalds * while others support intervals of up to 1024 milliseconds.
15441da177e4SLinus Torvalds * Isochronous URBs also have transfer intervals. (Note that for isochronous
15451da177e4SLinus Torvalds * endpoints, as well as high speed interrupt endpoints, the encoding of
15461da177e4SLinus Torvalds * the transfer interval in the endpoint descriptor is logarithmic.
15471da177e4SLinus Torvalds * Device drivers must convert that value to linear units themselves.)
15481da177e4SLinus Torvalds *
1549a03bede5SAlan Stern * If an isochronous endpoint queue isn't already running, the host
1550a03bede5SAlan Stern * controller will schedule a new URB to start as soon as bandwidth
1551a03bede5SAlan Stern * utilization allows. If the queue is running then a new URB will be
1552a03bede5SAlan Stern * scheduled to start in the first transfer slot following the end of the
1553a03bede5SAlan Stern * preceding URB, if that slot has not already expired. If the slot has
1554a03bede5SAlan Stern * expired (which can happen when IRQ delivery is delayed for a long time),
1555a03bede5SAlan Stern * the scheduling behavior depends on the URB_ISO_ASAP flag. If the flag
1556a03bede5SAlan Stern * is clear then the URB will be scheduled to start in the expired slot,
1557a03bede5SAlan Stern * implying that some of its packets will not be transferred; if the flag
1558a03bede5SAlan Stern * is set then the URB will be scheduled in the first unexpired slot,
1559a03bede5SAlan Stern * breaking the queue's synchronization. Upon URB completion, the
1560a03bede5SAlan Stern * start_frame field will be set to the (micro)frame number in which the
1561a03bede5SAlan Stern * transfer was scheduled. Ranges for frame counter values are HC-specific
1562a03bede5SAlan Stern * and can go from as low as 256 to as high as 65536 frames.
15631da177e4SLinus Torvalds *
15641da177e4SLinus Torvalds * Isochronous URBs have a different data transfer model, in part because
15651da177e4SLinus Torvalds * the quality of service is only "best effort". Callers provide specially
15661da177e4SLinus Torvalds * allocated URBs, with number_of_packets worth of iso_frame_desc structures
15671da177e4SLinus Torvalds * at the end. Each such packet is an individual ISO transfer. Isochronous
15681da177e4SLinus Torvalds * URBs are normally queued, submitted by drivers to arrange that
15691da177e4SLinus Torvalds * transfers are at least double buffered, and then explicitly resubmitted
15701da177e4SLinus Torvalds * in completion handlers, so
15711da177e4SLinus Torvalds * that data (such as audio or video) streams at as constant a rate as the
15721da177e4SLinus Torvalds * host controller scheduler can support.
15731da177e4SLinus Torvalds *
15741da177e4SLinus Torvalds * Completion Callbacks:
15751da177e4SLinus Torvalds *
15761da177e4SLinus Torvalds * The completion callback is made in_interrupt(), and one of the first
15771da177e4SLinus Torvalds * things that a completion handler should do is check the status field.
15781da177e4SLinus Torvalds * The status field is provided for all URBs. It is used to report
15791da177e4SLinus Torvalds * unlinked URBs, and status for all non-ISO transfers. It should not
15801da177e4SLinus Torvalds * be examined before the URB is returned to the completion handler.
15811da177e4SLinus Torvalds *
15821da177e4SLinus Torvalds * The context field is normally used to link URBs back to the relevant
15831da177e4SLinus Torvalds * driver or request state.
15841da177e4SLinus Torvalds *
15851da177e4SLinus Torvalds * When the completion callback is invoked for non-isochronous URBs, the
15861da177e4SLinus Torvalds * actual_length field tells how many bytes were transferred. This field
15871da177e4SLinus Torvalds * is updated even when the URB terminated with an error or was unlinked.
15881da177e4SLinus Torvalds *
15891da177e4SLinus Torvalds * ISO transfer status is reported in the status and actual_length fields
15901da177e4SLinus Torvalds * of the iso_frame_desc array, and the number of errors is reported in
15911da177e4SLinus Torvalds * error_count. Completion callbacks for ISO transfers will normally
15921da177e4SLinus Torvalds * (re)submit URBs to ensure a constant transfer rate.
1593719df469SRoman Kagan *
1594719df469SRoman Kagan * Note that even fields marked "public" should not be touched by the driver
1595719df469SRoman Kagan * when the urb is owned by the hcd, that is, since the call to
1596719df469SRoman Kagan * usb_submit_urb() till the entry into the completion routine.
15971da177e4SLinus Torvalds */
1598969ab2eeSGreg Kroah-Hartman struct urb {
1599aeec46b9SMartin Waitz /* private: usb core and host controller only fields in the urb */
16001da177e4SLinus Torvalds struct kref kref; /* reference count of the URB */
16018e6b8594SGreg Kroah-Hartman int unlinked; /* unlink error code */
16021da177e4SLinus Torvalds void *hcpriv; /* private data for host controller */
16031da177e4SLinus Torvalds atomic_t use_count; /* concurrent submissions counter */
160449367d8fSMing Lei atomic_t reject; /* submissions will fail */
16051da177e4SLinus Torvalds
1606aeec46b9SMartin Waitz /* public: documented fields in the urb that can be used by drivers */
1607b724ae77SAlan Stern struct list_head urb_list; /* list head for use by the urb's
1608b724ae77SAlan Stern * current owner */
1609969ab2eeSGreg Kroah-Hartman struct list_head anchor_list; /* the URB may be anchored */
161051a2f077SOliver Neukum struct usb_anchor *anchor;
16111da177e4SLinus Torvalds struct usb_device *dev; /* (in) pointer to associated device */
1612969ab2eeSGreg Kroah-Hartman struct usb_host_endpoint *ep; /* (internal) pointer to endpoint */
16131da177e4SLinus Torvalds unsigned int pipe; /* (in) pipe information */
161494af1220SSarah Sharp unsigned int stream_id; /* (in) stream ID */
16151da177e4SLinus Torvalds int status; /* (return) non-ISO status */
16161da177e4SLinus Torvalds unsigned int transfer_flags; /* (in) URB_SHORT_NOT_OK | ...*/
16171da177e4SLinus Torvalds void *transfer_buffer; /* (in) associated data buffer */
16181da177e4SLinus Torvalds dma_addr_t transfer_dma; /* (in) dma addr for transfer_buffer */
1619910f8d0cSMatthew Wilcox struct scatterlist *sg; /* (in) scatter gather buffer list */
1620bc677d5bSClemens Ladisch int num_mapped_sgs; /* (internal) mapped sg entries */
1621e04748e3SSarah Sharp int num_sgs; /* (in) number of entries in the sg list */
162216e2e5f6SGreg Kroah-Hartman u32 transfer_buffer_length; /* (in) data buffer length */
16238c209e67SGreg Kroah-Hartman u32 actual_length; /* (return) actual transfer length */
16241da177e4SLinus Torvalds unsigned char *setup_packet; /* (in) setup packet (control only) */
16251da177e4SLinus Torvalds dma_addr_t setup_dma; /* (in) dma addr for setup_packet */
16261da177e4SLinus Torvalds int start_frame; /* (modify) start frame (ISO) */
16271da177e4SLinus Torvalds int number_of_packets; /* (in) number of ISO packets */
1628b724ae77SAlan Stern int interval; /* (modify) transfer interval
1629b724ae77SAlan Stern * (INT/ISO) */
16301da177e4SLinus Torvalds int error_count; /* (return) number of ISO errors */
16311da177e4SLinus Torvalds void *context; /* (in) context for completion */
16321da177e4SLinus Torvalds usb_complete_t complete; /* (in) completion routine */
16336bc3f397SGustavo A. R. Silva struct usb_iso_packet_descriptor iso_frame_desc[];
1634b724ae77SAlan Stern /* (in) ISO ONLY */
16351da177e4SLinus Torvalds };
16361da177e4SLinus Torvalds
1637b724ae77SAlan Stern /* ----------------------------------------------------------------------- */
16381da177e4SLinus Torvalds
16391da177e4SLinus Torvalds /**
16401da177e4SLinus Torvalds * usb_fill_control_urb - initializes a control urb
16411da177e4SLinus Torvalds * @urb: pointer to the urb to initialize.
16421da177e4SLinus Torvalds * @dev: pointer to the struct usb_device for this urb.
16431da177e4SLinus Torvalds * @pipe: the endpoint pipe
164428e1ff70SRicardo Ribalda * @setup_packet: pointer to the setup_packet buffer. The buffer must be
164528e1ff70SRicardo Ribalda * suitable for DMA.
164628e1ff70SRicardo Ribalda * @transfer_buffer: pointer to the transfer buffer. The buffer must be
164728e1ff70SRicardo Ribalda * suitable for DMA.
16481da177e4SLinus Torvalds * @buffer_length: length of the transfer buffer
16493d5b2510SJesper Juhl * @complete_fn: pointer to the usb_complete_t function
16501da177e4SLinus Torvalds * @context: what to set the urb context to.
16511da177e4SLinus Torvalds *
16521da177e4SLinus Torvalds * Initializes a control urb with the proper information needed to submit
16531da177e4SLinus Torvalds * it to a device.
165428e1ff70SRicardo Ribalda *
165528e1ff70SRicardo Ribalda * The transfer buffer and the setup_packet buffer will most likely be filled
165628e1ff70SRicardo Ribalda * or read via DMA. The simplest way to get a buffer that can be DMAed to is
165728e1ff70SRicardo Ribalda * allocating it via kmalloc() or equivalent, even for very small buffers.
165828e1ff70SRicardo Ribalda * If the buffers are embedded in a bigger structure, there is a risk that
165928e1ff70SRicardo Ribalda * the buffer itself, the previous fields and/or the next fields are corrupted
166028e1ff70SRicardo Ribalda * due to cache incoherencies; or slowed down if they are evicted from the
166128e1ff70SRicardo Ribalda * cache. For more information, check &struct urb.
166228e1ff70SRicardo Ribalda *
16631da177e4SLinus Torvalds */
usb_fill_control_urb(struct urb * urb,struct usb_device * dev,unsigned int pipe,unsigned char * setup_packet,void * transfer_buffer,int buffer_length,usb_complete_t complete_fn,void * context)16641da177e4SLinus Torvalds static inline void usb_fill_control_urb(struct urb *urb,
16651da177e4SLinus Torvalds struct usb_device *dev,
16661da177e4SLinus Torvalds unsigned int pipe,
16671da177e4SLinus Torvalds unsigned char *setup_packet,
16681da177e4SLinus Torvalds void *transfer_buffer,
16691da177e4SLinus Torvalds int buffer_length,
16703d5b2510SJesper Juhl usb_complete_t complete_fn,
16711da177e4SLinus Torvalds void *context)
16721da177e4SLinus Torvalds {
16731da177e4SLinus Torvalds urb->dev = dev;
16741da177e4SLinus Torvalds urb->pipe = pipe;
16751da177e4SLinus Torvalds urb->setup_packet = setup_packet;
16761da177e4SLinus Torvalds urb->transfer_buffer = transfer_buffer;
16771da177e4SLinus Torvalds urb->transfer_buffer_length = buffer_length;
16783d5b2510SJesper Juhl urb->complete = complete_fn;
16791da177e4SLinus Torvalds urb->context = context;
16801da177e4SLinus Torvalds }
16811da177e4SLinus Torvalds
16821da177e4SLinus Torvalds /**
16831da177e4SLinus Torvalds * usb_fill_bulk_urb - macro to help initialize a bulk urb
16841da177e4SLinus Torvalds * @urb: pointer to the urb to initialize.
16851da177e4SLinus Torvalds * @dev: pointer to the struct usb_device for this urb.
16861da177e4SLinus Torvalds * @pipe: the endpoint pipe
168728e1ff70SRicardo Ribalda * @transfer_buffer: pointer to the transfer buffer. The buffer must be
168828e1ff70SRicardo Ribalda * suitable for DMA.
16891da177e4SLinus Torvalds * @buffer_length: length of the transfer buffer
16903d5b2510SJesper Juhl * @complete_fn: pointer to the usb_complete_t function
16911da177e4SLinus Torvalds * @context: what to set the urb context to.
16921da177e4SLinus Torvalds *
16931da177e4SLinus Torvalds * Initializes a bulk urb with the proper information needed to submit it
16941da177e4SLinus Torvalds * to a device.
169528e1ff70SRicardo Ribalda *
169628e1ff70SRicardo Ribalda * Refer to usb_fill_control_urb() for a description of the requirements for
169728e1ff70SRicardo Ribalda * transfer_buffer.
16981da177e4SLinus Torvalds */
usb_fill_bulk_urb(struct urb * urb,struct usb_device * dev,unsigned int pipe,void * transfer_buffer,int buffer_length,usb_complete_t complete_fn,void * context)16991da177e4SLinus Torvalds static inline void usb_fill_bulk_urb(struct urb *urb,
17001da177e4SLinus Torvalds struct usb_device *dev,
17011da177e4SLinus Torvalds unsigned int pipe,
17021da177e4SLinus Torvalds void *transfer_buffer,
17031da177e4SLinus Torvalds int buffer_length,
17043d5b2510SJesper Juhl usb_complete_t complete_fn,
17051da177e4SLinus Torvalds void *context)
17061da177e4SLinus Torvalds {
17071da177e4SLinus Torvalds urb->dev = dev;
17081da177e4SLinus Torvalds urb->pipe = pipe;
17091da177e4SLinus Torvalds urb->transfer_buffer = transfer_buffer;
17101da177e4SLinus Torvalds urb->transfer_buffer_length = buffer_length;
17113d5b2510SJesper Juhl urb->complete = complete_fn;
17121da177e4SLinus Torvalds urb->context = context;
17131da177e4SLinus Torvalds }
17141da177e4SLinus Torvalds
17151da177e4SLinus Torvalds /**
17161da177e4SLinus Torvalds * usb_fill_int_urb - macro to help initialize a interrupt urb
17171da177e4SLinus Torvalds * @urb: pointer to the urb to initialize.
17181da177e4SLinus Torvalds * @dev: pointer to the struct usb_device for this urb.
17191da177e4SLinus Torvalds * @pipe: the endpoint pipe
172028e1ff70SRicardo Ribalda * @transfer_buffer: pointer to the transfer buffer. The buffer must be
172128e1ff70SRicardo Ribalda * suitable for DMA.
17221da177e4SLinus Torvalds * @buffer_length: length of the transfer buffer
17233d5b2510SJesper Juhl * @complete_fn: pointer to the usb_complete_t function
17241da177e4SLinus Torvalds * @context: what to set the urb context to.
17251da177e4SLinus Torvalds * @interval: what to set the urb interval to, encoded like
17261da177e4SLinus Torvalds * the endpoint descriptor's bInterval value.
17271da177e4SLinus Torvalds *
17281da177e4SLinus Torvalds * Initializes a interrupt urb with the proper information needed to submit
17291da177e4SLinus Torvalds * it to a device.
1730f09a15e6SMatthew Wilcox *
173128e1ff70SRicardo Ribalda * Refer to usb_fill_control_urb() for a description of the requirements for
173228e1ff70SRicardo Ribalda * transfer_buffer.
173328e1ff70SRicardo Ribalda *
1734fca504f6SOliver Neukum * Note that High Speed and SuperSpeed(+) interrupt endpoints use a logarithmic
1735f09a15e6SMatthew Wilcox * encoding of the endpoint interval, and express polling intervals in
1736f09a15e6SMatthew Wilcox * microframes (eight per millisecond) rather than in frames (one per
1737f09a15e6SMatthew Wilcox * millisecond).
17381da177e4SLinus Torvalds */
usb_fill_int_urb(struct urb * urb,struct usb_device * dev,unsigned int pipe,void * transfer_buffer,int buffer_length,usb_complete_t complete_fn,void * context,int interval)17391da177e4SLinus Torvalds static inline void usb_fill_int_urb(struct urb *urb,
17401da177e4SLinus Torvalds struct usb_device *dev,
17411da177e4SLinus Torvalds unsigned int pipe,
17421da177e4SLinus Torvalds void *transfer_buffer,
17431da177e4SLinus Torvalds int buffer_length,
17443d5b2510SJesper Juhl usb_complete_t complete_fn,
17451da177e4SLinus Torvalds void *context,
17461da177e4SLinus Torvalds int interval)
17471da177e4SLinus Torvalds {
17481da177e4SLinus Torvalds urb->dev = dev;
17491da177e4SLinus Torvalds urb->pipe = pipe;
17501da177e4SLinus Torvalds urb->transfer_buffer = transfer_buffer;
17511da177e4SLinus Torvalds urb->transfer_buffer_length = buffer_length;
17523d5b2510SJesper Juhl urb->complete = complete_fn;
17531da177e4SLinus Torvalds urb->context = context;
175442189d85SFelipe Balbi
1755fca504f6SOliver Neukum if (dev->speed == USB_SPEED_HIGH || dev->speed >= USB_SPEED_SUPER) {
175642189d85SFelipe Balbi /* make sure interval is within allowed range */
175742189d85SFelipe Balbi interval = clamp(interval, 1, 16);
175842189d85SFelipe Balbi
17591da177e4SLinus Torvalds urb->interval = 1 << (interval - 1);
176042189d85SFelipe Balbi } else {
17611da177e4SLinus Torvalds urb->interval = interval;
176242189d85SFelipe Balbi }
176342189d85SFelipe Balbi
17641da177e4SLinus Torvalds urb->start_frame = -1;
17651da177e4SLinus Torvalds }
17661da177e4SLinus Torvalds
17671da177e4SLinus Torvalds extern void usb_init_urb(struct urb *urb);
176855016f10SAl Viro extern struct urb *usb_alloc_urb(int iso_packets, gfp_t mem_flags);
17691da177e4SLinus Torvalds extern void usb_free_urb(struct urb *urb);
17701da177e4SLinus Torvalds #define usb_put_urb usb_free_urb
17711da177e4SLinus Torvalds extern struct urb *usb_get_urb(struct urb *urb);
177255016f10SAl Viro extern int usb_submit_urb(struct urb *urb, gfp_t mem_flags);
17731da177e4SLinus Torvalds extern int usb_unlink_urb(struct urb *urb);
17741da177e4SLinus Torvalds extern void usb_kill_urb(struct urb *urb);
177555b447bfSOliver Neukum extern void usb_poison_urb(struct urb *urb);
177655b447bfSOliver Neukum extern void usb_unpoison_urb(struct urb *urb);
17778815bb09SOliver Neukum extern void usb_block_urb(struct urb *urb);
177851a2f077SOliver Neukum extern void usb_kill_anchored_urbs(struct usb_anchor *anchor);
17796a2839beSOliver Neukum extern void usb_poison_anchored_urbs(struct usb_anchor *anchor);
1780856395d6SOliver Neukum extern void usb_unpoison_anchored_urbs(struct usb_anchor *anchor);
1781eda76959SOliver Neukum extern void usb_unlink_anchored_urbs(struct usb_anchor *anchor);
17826ec4147eSHans de Goede extern void usb_anchor_suspend_wakeups(struct usb_anchor *anchor);
17836ec4147eSHans de Goede extern void usb_anchor_resume_wakeups(struct usb_anchor *anchor);
178451a2f077SOliver Neukum extern void usb_anchor_urb(struct urb *urb, struct usb_anchor *anchor);
178551a2f077SOliver Neukum extern void usb_unanchor_urb(struct urb *urb);
178651a2f077SOliver Neukum extern int usb_wait_anchor_empty_timeout(struct usb_anchor *anchor,
178751a2f077SOliver Neukum unsigned int timeout);
178819876252SOliver Neukum extern struct urb *usb_get_from_anchor(struct usb_anchor *anchor);
178919876252SOliver Neukum extern void usb_scuttle_anchored_urbs(struct usb_anchor *anchor);
179019876252SOliver Neukum extern int usb_anchor_empty(struct usb_anchor *anchor);
17911da177e4SLinus Torvalds
17928815bb09SOliver Neukum #define usb_unblock_urb usb_unpoison_urb
17938815bb09SOliver Neukum
1794fea34091SAlan Stern /**
1795fea34091SAlan Stern * usb_urb_dir_in - check if an URB describes an IN transfer
1796fea34091SAlan Stern * @urb: URB to be checked
1797fea34091SAlan Stern *
1798626f090cSYacine Belkadi * Return: 1 if @urb describes an IN transfer (device-to-host),
1799fea34091SAlan Stern * otherwise 0.
1800fea34091SAlan Stern */
usb_urb_dir_in(struct urb * urb)1801fea34091SAlan Stern static inline int usb_urb_dir_in(struct urb *urb)
1802fea34091SAlan Stern {
1803d617bc83SAlan Stern return (urb->transfer_flags & URB_DIR_MASK) == URB_DIR_IN;
1804fea34091SAlan Stern }
1805fea34091SAlan Stern
1806fea34091SAlan Stern /**
1807fea34091SAlan Stern * usb_urb_dir_out - check if an URB describes an OUT transfer
1808fea34091SAlan Stern * @urb: URB to be checked
1809fea34091SAlan Stern *
1810626f090cSYacine Belkadi * Return: 1 if @urb describes an OUT transfer (host-to-device),
1811fea34091SAlan Stern * otherwise 0.
1812fea34091SAlan Stern */
usb_urb_dir_out(struct urb * urb)1813fea34091SAlan Stern static inline int usb_urb_dir_out(struct urb *urb)
1814fea34091SAlan Stern {
1815fea34091SAlan Stern return (urb->transfer_flags & URB_DIR_MASK) == URB_DIR_OUT;
1816fea34091SAlan Stern }
1817fea34091SAlan Stern
1818fcc2cc1fSGreg Kroah-Hartman int usb_pipe_type_check(struct usb_device *dev, unsigned int pipe);
1819e901b987STakashi Iwai int usb_urb_ep_type_check(const struct urb *urb);
1820e901b987STakashi Iwai
1821073900a2SDaniel Mack void *usb_alloc_coherent(struct usb_device *dev, size_t size,
182255016f10SAl Viro gfp_t mem_flags, dma_addr_t *dma);
1823073900a2SDaniel Mack void usb_free_coherent(struct usb_device *dev, size_t size,
18241da177e4SLinus Torvalds void *addr, dma_addr_t dma);
18251da177e4SLinus Torvalds
18261da177e4SLinus Torvalds #if 0
18271da177e4SLinus Torvalds struct urb *usb_buffer_map(struct urb *urb);
18281da177e4SLinus Torvalds void usb_buffer_dmasync(struct urb *urb);
18291da177e4SLinus Torvalds void usb_buffer_unmap(struct urb *urb);
18301da177e4SLinus Torvalds #endif
18311da177e4SLinus Torvalds
18321da177e4SLinus Torvalds struct scatterlist;
18335e60a161SAlan Stern int usb_buffer_map_sg(const struct usb_device *dev, int is_in,
18341da177e4SLinus Torvalds struct scatterlist *sg, int nents);
18351da177e4SLinus Torvalds #if 0
18365e60a161SAlan Stern void usb_buffer_dmasync_sg(const struct usb_device *dev, int is_in,
18371da177e4SLinus Torvalds struct scatterlist *sg, int n_hw_ents);
18381da177e4SLinus Torvalds #endif
18395e60a161SAlan Stern void usb_buffer_unmap_sg(const struct usb_device *dev, int is_in,
18401da177e4SLinus Torvalds struct scatterlist *sg, int n_hw_ents);
18411da177e4SLinus Torvalds
18421da177e4SLinus Torvalds /*-------------------------------------------------------------------*
18431da177e4SLinus Torvalds * SYNCHRONOUS CALL SUPPORT *
18441da177e4SLinus Torvalds *-------------------------------------------------------------------*/
18451da177e4SLinus Torvalds
18461da177e4SLinus Torvalds extern int usb_control_msg(struct usb_device *dev, unsigned int pipe,
18471da177e4SLinus Torvalds __u8 request, __u8 requesttype, __u16 value, __u16 index,
18481da177e4SLinus Torvalds void *data, __u16 size, int timeout);
1849782a7a63SGreg Kroah-Hartman extern int usb_interrupt_msg(struct usb_device *usb_dev, unsigned int pipe,
1850782a7a63SGreg Kroah-Hartman void *data, int len, int *actual_length, int timeout);
18511da177e4SLinus Torvalds extern int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
18521da177e4SLinus Torvalds void *data, int len, int *actual_length,
18531da177e4SLinus Torvalds int timeout);
18541da177e4SLinus Torvalds
18551da177e4SLinus Torvalds /* wrappers around usb_control_msg() for the most common standard requests */
1856719b8f28SGreg Kroah-Hartman int usb_control_msg_send(struct usb_device *dev, __u8 endpoint, __u8 request,
1857719b8f28SGreg Kroah-Hartman __u8 requesttype, __u16 value, __u16 index,
1858ddd1198eSOliver Neukum const void *data, __u16 size, int timeout,
1859ddd1198eSOliver Neukum gfp_t memflags);
1860719b8f28SGreg Kroah-Hartman int usb_control_msg_recv(struct usb_device *dev, __u8 endpoint, __u8 request,
1861719b8f28SGreg Kroah-Hartman __u8 requesttype, __u16 value, __u16 index,
1862ddd1198eSOliver Neukum void *data, __u16 size, int timeout,
1863ddd1198eSOliver Neukum gfp_t memflags);
18641da177e4SLinus Torvalds extern int usb_get_descriptor(struct usb_device *dev, unsigned char desctype,
18651da177e4SLinus Torvalds unsigned char descindex, void *buf, int size);
18661da177e4SLinus Torvalds extern int usb_get_status(struct usb_device *dev,
18672e43f0feSFelipe Balbi int recip, int type, int target, void *data);
1868d9e1e148SFelipe Balbi
usb_get_std_status(struct usb_device * dev,int recip,int target,void * data)1869d9e1e148SFelipe Balbi static inline int usb_get_std_status(struct usb_device *dev,
1870d9e1e148SFelipe Balbi int recip, int target, void *data)
1871d9e1e148SFelipe Balbi {
18722e43f0feSFelipe Balbi return usb_get_status(dev, recip, USB_STATUS_TYPE_STANDARD, target,
18732e43f0feSFelipe Balbi data);
1874d9e1e148SFelipe Balbi }
1875d9e1e148SFelipe Balbi
usb_get_ptm_status(struct usb_device * dev,void * data)1876f8f3e4acSFelipe Balbi static inline int usb_get_ptm_status(struct usb_device *dev, void *data)
1877f8f3e4acSFelipe Balbi {
1878f8f3e4acSFelipe Balbi return usb_get_status(dev, USB_RECIP_DEVICE, USB_STATUS_TYPE_PTM,
1879f8f3e4acSFelipe Balbi 0, data);
1880f8f3e4acSFelipe Balbi }
1881f8f3e4acSFelipe Balbi
18821da177e4SLinus Torvalds extern int usb_string(struct usb_device *dev, int index,
18831da177e4SLinus Torvalds char *buf, size_t size);
1884983055bfSVincent Mailhol extern char *usb_cache_string(struct usb_device *udev, int index);
18851da177e4SLinus Torvalds
18861da177e4SLinus Torvalds /* wrappers that also update important state inside usbcore */
18871da177e4SLinus Torvalds extern int usb_clear_halt(struct usb_device *dev, int pipe);
18881da177e4SLinus Torvalds extern int usb_reset_configuration(struct usb_device *dev);
18891da177e4SLinus Torvalds extern int usb_set_interface(struct usb_device *dev, int ifnum, int alternate);
18903444b26aSDavid Vrabel extern void usb_reset_endpoint(struct usb_device *dev, unsigned int epaddr);
18911da177e4SLinus Torvalds
1892088dc270SAlan Stern /* this request isn't really synchronous, but it belongs with the others */
1893088dc270SAlan Stern extern int usb_driver_set_configuration(struct usb_device *udev, int config);
1894088dc270SAlan Stern
1895b7945b77SValentina Manea /* choose and set configuration for device */
1896b7945b77SValentina Manea extern int usb_choose_configuration(struct usb_device *udev);
1897b7945b77SValentina Manea extern int usb_set_configuration(struct usb_device *dev, int configuration);
1898b7945b77SValentina Manea
18991da177e4SLinus Torvalds /*
19001da177e4SLinus Torvalds * timeouts, in milliseconds, used for sending/receiving control messages
19011da177e4SLinus Torvalds * they typically complete within a few frames (msec) after they're issued
19021da177e4SLinus Torvalds * USB identifies 5 second timeouts, maybe more in a few cases, and a few
19031da177e4SLinus Torvalds * slow devices (like some MGE Ellipse UPSes) actually push that limit.
19041da177e4SLinus Torvalds */
19051da177e4SLinus Torvalds #define USB_CTRL_GET_TIMEOUT 5000
19061da177e4SLinus Torvalds #define USB_CTRL_SET_TIMEOUT 5000
19071da177e4SLinus Torvalds
19081da177e4SLinus Torvalds
19091da177e4SLinus Torvalds /**
19101da177e4SLinus Torvalds * struct usb_sg_request - support for scatter/gather I/O
19111da177e4SLinus Torvalds * @status: zero indicates success, else negative errno
19121da177e4SLinus Torvalds * @bytes: counts bytes transferred.
19131da177e4SLinus Torvalds *
19141da177e4SLinus Torvalds * These requests are initialized using usb_sg_init(), and then are used
19151da177e4SLinus Torvalds * as request handles passed to usb_sg_wait() or usb_sg_cancel(). Most
19161da177e4SLinus Torvalds * members of the request object aren't for driver access.
19171da177e4SLinus Torvalds *
19181da177e4SLinus Torvalds * The status and bytecount values are valid only after usb_sg_wait()
19191da177e4SLinus Torvalds * returns. If the status is zero, then the bytecount matches the total
19201da177e4SLinus Torvalds * from the request.
19211da177e4SLinus Torvalds *
19221da177e4SLinus Torvalds * After an error completion, drivers may need to clear a halt condition
19231da177e4SLinus Torvalds * on the endpoint.
19241da177e4SLinus Torvalds */
19251da177e4SLinus Torvalds struct usb_sg_request {
19261da177e4SLinus Torvalds int status;
19271da177e4SLinus Torvalds size_t bytes;
19281da177e4SLinus Torvalds
1929bf92c190SRandy Dunlap /* private:
1930bf92c190SRandy Dunlap * members below are private to usbcore,
19311da177e4SLinus Torvalds * and are not provided for driver access!
19321da177e4SLinus Torvalds */
19331da177e4SLinus Torvalds spinlock_t lock;
19341da177e4SLinus Torvalds
19351da177e4SLinus Torvalds struct usb_device *dev;
19361da177e4SLinus Torvalds int pipe;
19371da177e4SLinus Torvalds
19381da177e4SLinus Torvalds int entries;
19391da177e4SLinus Torvalds struct urb **urbs;
19401da177e4SLinus Torvalds
19411da177e4SLinus Torvalds int count;
19421da177e4SLinus Torvalds struct completion complete;
19431da177e4SLinus Torvalds };
19441da177e4SLinus Torvalds
19451da177e4SLinus Torvalds int usb_sg_init(
19461da177e4SLinus Torvalds struct usb_sg_request *io,
19471da177e4SLinus Torvalds struct usb_device *dev,
19481da177e4SLinus Torvalds unsigned pipe,
19491da177e4SLinus Torvalds unsigned period,
19501da177e4SLinus Torvalds struct scatterlist *sg,
19511da177e4SLinus Torvalds int nents,
19521da177e4SLinus Torvalds size_t length,
195355016f10SAl Viro gfp_t mem_flags
19541da177e4SLinus Torvalds );
19551da177e4SLinus Torvalds void usb_sg_cancel(struct usb_sg_request *io);
19561da177e4SLinus Torvalds void usb_sg_wait(struct usb_sg_request *io);
19571da177e4SLinus Torvalds
19581da177e4SLinus Torvalds
1959b724ae77SAlan Stern /* ----------------------------------------------------------------------- */
19601da177e4SLinus Torvalds
19611da177e4SLinus Torvalds /*
19621da177e4SLinus Torvalds * For various legacy reasons, Linux has a small cookie that's paired with
19631da177e4SLinus Torvalds * a struct usb_device to identify an endpoint queue. Queue characteristics
19641da177e4SLinus Torvalds * are defined by the endpoint's descriptor. This cookie is called a "pipe",
19651da177e4SLinus Torvalds * an unsigned int encoded as:
19661da177e4SLinus Torvalds *
19671da177e4SLinus Torvalds * - direction: bit 7 (0 = Host-to-Device [Out],
19681da177e4SLinus Torvalds * 1 = Device-to-Host [In] ...
19691da177e4SLinus Torvalds * like endpoint bEndpointAddress)
19701da177e4SLinus Torvalds * - device address: bits 8-14 ... bit positions known to uhci-hcd
19711da177e4SLinus Torvalds * - endpoint: bits 15-18 ... bit positions known to uhci-hcd
19721da177e4SLinus Torvalds * - pipe type: bits 30-31 (00 = isochronous, 01 = interrupt,
19731da177e4SLinus Torvalds * 10 = control, 11 = bulk)
19741da177e4SLinus Torvalds *
19751da177e4SLinus Torvalds * Given the device address and endpoint descriptor, pipes are redundant.
19761da177e4SLinus Torvalds */
19771da177e4SLinus Torvalds
19781da177e4SLinus Torvalds /* NOTE: these are not the standard USB_ENDPOINT_XFER_* values!! */
19791da177e4SLinus Torvalds /* (yet ... they're the values used by usbfs) */
19801da177e4SLinus Torvalds #define PIPE_ISOCHRONOUS 0
19811da177e4SLinus Torvalds #define PIPE_INTERRUPT 1
19821da177e4SLinus Torvalds #define PIPE_CONTROL 2
19831da177e4SLinus Torvalds #define PIPE_BULK 3
19841da177e4SLinus Torvalds
19851da177e4SLinus Torvalds #define usb_pipein(pipe) ((pipe) & USB_DIR_IN)
19861da177e4SLinus Torvalds #define usb_pipeout(pipe) (!usb_pipein(pipe))
19871da177e4SLinus Torvalds
19881da177e4SLinus Torvalds #define usb_pipedevice(pipe) (((pipe) >> 8) & 0x7f)
19891da177e4SLinus Torvalds #define usb_pipeendpoint(pipe) (((pipe) >> 15) & 0xf)
19901da177e4SLinus Torvalds
19911da177e4SLinus Torvalds #define usb_pipetype(pipe) (((pipe) >> 30) & 3)
19921da177e4SLinus Torvalds #define usb_pipeisoc(pipe) (usb_pipetype((pipe)) == PIPE_ISOCHRONOUS)
19931da177e4SLinus Torvalds #define usb_pipeint(pipe) (usb_pipetype((pipe)) == PIPE_INTERRUPT)
19941da177e4SLinus Torvalds #define usb_pipecontrol(pipe) (usb_pipetype((pipe)) == PIPE_CONTROL)
19951da177e4SLinus Torvalds #define usb_pipebulk(pipe) (usb_pipetype((pipe)) == PIPE_BULK)
19961da177e4SLinus Torvalds
__create_pipe(struct usb_device * dev,unsigned int endpoint)1997b724ae77SAlan Stern static inline unsigned int __create_pipe(struct usb_device *dev,
1998b724ae77SAlan Stern unsigned int endpoint)
19991da177e4SLinus Torvalds {
20001da177e4SLinus Torvalds return (dev->devnum << 8) | (endpoint << 15);
20011da177e4SLinus Torvalds }
20021da177e4SLinus Torvalds
20031da177e4SLinus Torvalds /* Create various pipes... */
2004b724ae77SAlan Stern #define usb_sndctrlpipe(dev, endpoint) \
2005b724ae77SAlan Stern ((PIPE_CONTROL << 30) | __create_pipe(dev, endpoint))
2006b724ae77SAlan Stern #define usb_rcvctrlpipe(dev, endpoint) \
2007b724ae77SAlan Stern ((PIPE_CONTROL << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
2008b724ae77SAlan Stern #define usb_sndisocpipe(dev, endpoint) \
2009b724ae77SAlan Stern ((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev, endpoint))
2010b724ae77SAlan Stern #define usb_rcvisocpipe(dev, endpoint) \
2011b724ae77SAlan Stern ((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
2012b724ae77SAlan Stern #define usb_sndbulkpipe(dev, endpoint) \
2013b724ae77SAlan Stern ((PIPE_BULK << 30) | __create_pipe(dev, endpoint))
2014b724ae77SAlan Stern #define usb_rcvbulkpipe(dev, endpoint) \
2015b724ae77SAlan Stern ((PIPE_BULK << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
2016b724ae77SAlan Stern #define usb_sndintpipe(dev, endpoint) \
2017b724ae77SAlan Stern ((PIPE_INTERRUPT << 30) | __create_pipe(dev, endpoint))
2018b724ae77SAlan Stern #define usb_rcvintpipe(dev, endpoint) \
2019b724ae77SAlan Stern ((PIPE_INTERRUPT << 30) | __create_pipe(dev, endpoint) | USB_DIR_IN)
20201da177e4SLinus Torvalds
2021fe54b058SMatthew Wilcox static inline struct usb_host_endpoint *
usb_pipe_endpoint(struct usb_device * dev,unsigned int pipe)2022fe54b058SMatthew Wilcox usb_pipe_endpoint(struct usb_device *dev, unsigned int pipe)
2023fe54b058SMatthew Wilcox {
2024fe54b058SMatthew Wilcox struct usb_host_endpoint **eps;
2025fe54b058SMatthew Wilcox eps = usb_pipein(pipe) ? dev->ep_in : dev->ep_out;
2026fe54b058SMatthew Wilcox return eps[usb_pipeendpoint(pipe)];
2027fe54b058SMatthew Wilcox }
2028fe54b058SMatthew Wilcox
usb_maxpacket(struct usb_device * udev,int pipe)20292ddf7617SVincent Mailhol static inline u16 usb_maxpacket(struct usb_device *udev, int pipe)
20301da177e4SLinus Torvalds {
2031bdddc253SVincent Mailhol struct usb_host_endpoint *ep = usb_pipe_endpoint(udev, pipe);
20320f08c2e7SVincent Mailhol
20331da177e4SLinus Torvalds if (!ep)
20341da177e4SLinus Torvalds return 0;
20351da177e4SLinus Torvalds
20361da177e4SLinus Torvalds /* NOTE: only 0x07ff bits are for packet size... */
203729cc8897SKuninori Morimoto return usb_endpoint_maxp(&ep->desc);
20381da177e4SLinus Torvalds }
20391da177e4SLinus Torvalds
20402c4d6bf2SJohan Hovold /* translate USB error codes to codes user space understands */
usb_translate_errors(int error_code)20412c4d6bf2SJohan Hovold static inline int usb_translate_errors(int error_code)
20422c4d6bf2SJohan Hovold {
20432c4d6bf2SJohan Hovold switch (error_code) {
20442c4d6bf2SJohan Hovold case 0:
20452c4d6bf2SJohan Hovold case -ENOMEM:
20462c4d6bf2SJohan Hovold case -ENODEV:
204767c88382SJohan Hovold case -EOPNOTSUPP:
20482c4d6bf2SJohan Hovold return error_code;
20492c4d6bf2SJohan Hovold default:
20502c4d6bf2SJohan Hovold return -EIO;
20512c4d6bf2SJohan Hovold }
20522c4d6bf2SJohan Hovold }
20532c4d6bf2SJohan Hovold
20543099e75aSGreg Kroah-Hartman /* Events from the usb core */
20553099e75aSGreg Kroah-Hartman #define USB_DEVICE_ADD 0x0001
20563099e75aSGreg Kroah-Hartman #define USB_DEVICE_REMOVE 0x0002
20573099e75aSGreg Kroah-Hartman #define USB_BUS_ADD 0x0003
20583099e75aSGreg Kroah-Hartman #define USB_BUS_REMOVE 0x0004
20593099e75aSGreg Kroah-Hartman extern void usb_register_notify(struct notifier_block *nb);
20603099e75aSGreg Kroah-Hartman extern void usb_unregister_notify(struct notifier_block *nb);
20613099e75aSGreg Kroah-Hartman
206200048b8bSGreg Kroah-Hartman /* debugfs stuff */
206300048b8bSGreg Kroah-Hartman extern struct dentry *usb_debug_root;
206400048b8bSGreg Kroah-Hartman
20650cfbd328SMichal Sojka /* LED triggers */
20660cfbd328SMichal Sojka enum usb_led_event {
20670cfbd328SMichal Sojka USB_LED_EVENT_HOST = 0,
20680cfbd328SMichal Sojka USB_LED_EVENT_GADGET = 1,
20690cfbd328SMichal Sojka };
20700cfbd328SMichal Sojka
20710cfbd328SMichal Sojka #ifdef CONFIG_USB_LED_TRIG
20720cfbd328SMichal Sojka extern void usb_led_activity(enum usb_led_event ev);
20730cfbd328SMichal Sojka #else
usb_led_activity(enum usb_led_event ev)20740cfbd328SMichal Sojka static inline void usb_led_activity(enum usb_led_event ev) {}
20750cfbd328SMichal Sojka #endif
20760cfbd328SMichal Sojka
20771da177e4SLinus Torvalds #endif /* __KERNEL__ */
20781da177e4SLinus Torvalds
20791da177e4SLinus Torvalds #endif
2080