LCOV - code coverage report
Current view: top level - include/linux - usb.h (source / functions) Hit Total Coverage
Test: gcov_data_raspi2_real_modules_combined.info Lines: 50 53 94.3 %
Date: 2020-09-30 20:25:40 Functions: 3 3 100.0 %
Branches: 13 42 31.0 %

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

Generated by: LCOV version 1.14