home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / src / linux-headers-2.6.17-6 / include / linux / usb.h < prev    next >
Encoding:
C/C++ Source or Header  |  2006-08-11  |  47.1 KB  |  1,210 lines
  1. #ifndef __LINUX_USB_H
  2. #define __LINUX_USB_H
  3.  
  4. #include <linux/mod_devicetable.h>
  5. #include <linux/usb_ch9.h>
  6.  
  7. #define USB_MAJOR            180
  8. #define USB_DEVICE_MAJOR        189
  9.  
  10.  
  11. #ifdef __KERNEL__
  12.  
  13. #include <linux/errno.h>        /* for -ENODEV */
  14. #include <linux/delay.h>    /* for mdelay() */
  15. #include <linux/interrupt.h>    /* for in_interrupt() */
  16. #include <linux/list.h>        /* for struct list_head */
  17. #include <linux/kref.h>        /* for struct kref */
  18. #include <linux/device.h>    /* for struct device */
  19. #include <linux/fs.h>        /* for struct file_operations */
  20. #include <linux/completion.h>    /* for struct completion */
  21. #include <linux/sched.h>    /* for current && schedule_timeout */
  22.  
  23. struct usb_device;
  24. struct usb_driver;
  25.  
  26. /*-------------------------------------------------------------------------*/
  27.  
  28. /*
  29.  * Host-side wrappers for standard USB descriptors ... these are parsed
  30.  * from the data provided by devices.  Parsing turns them from a flat
  31.  * sequence of descriptors into a hierarchy:
  32.  *
  33.  *  - devices have one (usually) or more configs;
  34.  *  - configs have one (often) or more interfaces;
  35.  *  - interfaces have one (usually) or more settings;
  36.  *  - each interface setting has zero or (usually) more endpoints.
  37.  *
  38.  * And there might be other descriptors mixed in with those.
  39.  *
  40.  * Devices may also have class-specific or vendor-specific descriptors.
  41.  */
  42.  
  43. /**
  44.  * struct usb_host_endpoint - host-side endpoint descriptor and queue
  45.  * @desc: descriptor for this endpoint, wMaxPacketSize in native byteorder
  46.  * @urb_list: urbs queued to this endpoint; maintained by usbcore
  47.  * @hcpriv: for use by HCD; typically holds hardware dma queue head (QH)
  48.  *    with one or more transfer descriptors (TDs) per urb
  49.  * @kobj: kobject for sysfs info
  50.  * @extra: descriptors following this endpoint in the configuration
  51.  * @extralen: how many bytes of "extra" are valid
  52.  *
  53.  * USB requests are always queued to a given endpoint, identified by a
  54.  * descriptor within an active interface in a given USB configuration.
  55.  */
  56. struct usb_host_endpoint {
  57.     struct usb_endpoint_descriptor    desc;
  58.     struct list_head        urb_list;
  59.     void                *hcpriv;
  60.     struct kobject            *kobj;    /* For sysfs info */
  61.  
  62.     unsigned char *extra;   /* Extra descriptors */
  63.     int extralen;
  64. };
  65.  
  66. /* host-side wrapper for one interface setting's parsed descriptors */
  67. struct usb_host_interface {
  68.     struct usb_interface_descriptor    desc;
  69.  
  70.     /* array of desc.bNumEndpoint endpoints associated with this
  71.      * interface setting.  these will be in no particular order.
  72.      */
  73.     struct usb_host_endpoint *endpoint;
  74.  
  75.     char *string;        /* iInterface string, if present */
  76.     unsigned char *extra;   /* Extra descriptors */
  77.     int extralen;
  78. };
  79.  
  80. enum usb_interface_condition {
  81.     USB_INTERFACE_UNBOUND = 0,
  82.     USB_INTERFACE_BINDING,
  83.     USB_INTERFACE_BOUND,
  84.     USB_INTERFACE_UNBINDING,
  85. };
  86.  
  87. /**
  88.  * struct usb_interface - what usb device drivers talk to
  89.  * @altsetting: array of interface structures, one for each alternate
  90.  *     setting that may be selected.  Each one includes a set of
  91.  *     endpoint configurations.  They will be in no particular order.
  92.  * @num_altsetting: number of altsettings defined.
  93.  * @cur_altsetting: the current altsetting.
  94.  * @driver: the USB driver that is bound to this interface.
  95.  * @minor: the minor number assigned to this interface, if this
  96.  *    interface is bound to a driver that uses the USB major number.
  97.  *    If this interface does not use the USB major, this field should
  98.  *    be unused.  The driver should set this value in the probe()
  99.  *    function of the driver, after it has been assigned a minor
  100.  *    number from the USB core by calling usb_register_dev().
  101.  * @condition: binding state of the interface: not bound, binding
  102.  *    (in probe()), bound to a driver, or unbinding (in disconnect())
  103.  * @dev: driver model's view of this device
  104.  * @class_dev: driver model's class view of this device.
  105.  *
  106.  * USB device drivers attach to interfaces on a physical device.  Each
  107.  * interface encapsulates a single high level function, such as feeding
  108.  * an audio stream to a speaker or reporting a change in a volume control.
  109.  * Many USB devices only have one interface.  The protocol used to talk to
  110.  * an interface's endpoints can be defined in a usb "class" specification,
  111.  * or by a product's vendor.  The (default) control endpoint is part of
  112.  * every interface, but is never listed among the interface's descriptors.
  113.  *
  114.  * The driver that is bound to the interface can use standard driver model
  115.  * calls such as dev_get_drvdata() on the dev member of this structure.
  116.  *
  117.  * Each interface may have alternate settings.  The initial configuration
  118.  * of a device sets altsetting 0, but the device driver can change
  119.  * that setting using usb_set_interface().  Alternate settings are often
  120.  * used to control the the use of periodic endpoints, such as by having
  121.  * different endpoints use different amounts of reserved USB bandwidth.
  122.  * All standards-conformant USB devices that use isochronous endpoints
  123.  * will use them in non-default settings.
  124.  *
  125.  * The USB specification says that alternate setting numbers must run from
  126.  * 0 to one less than the total number of alternate settings.  But some
  127.  * devices manage to mess this up, and the structures aren't necessarily
  128.  * stored in numerical order anyhow.  Use usb_altnum_to_altsetting() to
  129.  * look up an alternate setting in the altsetting array based on its number.
  130.  */
  131. struct usb_interface {
  132.     /* array of alternate settings for this interface,
  133.      * stored in no particular order */
  134.     struct usb_host_interface *altsetting;
  135.  
  136.     struct usb_host_interface *cur_altsetting;    /* the currently
  137.                      * active alternate setting */
  138.     unsigned num_altsetting;    /* number of alternate settings */
  139.  
  140.     int minor;            /* minor number this interface is
  141.                      * bound to */
  142.     enum usb_interface_condition condition;        /* state of binding */
  143.     struct device dev;        /* interface specific device info */
  144.     struct class_device *class_dev;
  145. };
  146. #define    to_usb_interface(d) container_of(d, struct usb_interface, dev)
  147. #define    interface_to_usbdev(intf) \
  148.     container_of(intf->dev.parent, struct usb_device, dev)
  149.  
  150. static inline void *usb_get_intfdata (struct usb_interface *intf)
  151. {
  152.     return dev_get_drvdata (&intf->dev);
  153. }
  154.  
  155. static inline void usb_set_intfdata (struct usb_interface *intf, void *data)
  156. {
  157.     dev_set_drvdata(&intf->dev, data);
  158. }
  159.  
  160. struct usb_interface *usb_get_intf(struct usb_interface *intf);
  161. void usb_put_intf(struct usb_interface *intf);
  162.  
  163. /* this maximum is arbitrary */
  164. #define USB_MAXINTERFACES    32
  165.  
  166. /**
  167.  * struct usb_interface_cache - long-term representation of a device interface
  168.  * @num_altsetting: number of altsettings defined.
  169.  * @ref: reference counter.
  170.  * @altsetting: variable-length array of interface structures, one for
  171.  *    each alternate setting that may be selected.  Each one includes a
  172.  *    set of endpoint configurations.  They will be in no particular order.
  173.  *
  174.  * These structures persist for the lifetime of a usb_device, unlike
  175.  * struct usb_interface (which persists only as long as its configuration
  176.  * is installed).  The altsetting arrays can be accessed through these
  177.  * structures at any time, permitting comparison of configurations and
  178.  * providing support for the /proc/bus/usb/devices pseudo-file.
  179.  */
  180. struct usb_interface_cache {
  181.     unsigned num_altsetting;    /* number of alternate settings */
  182.     struct kref ref;        /* reference counter */
  183.  
  184.     /* variable-length array of alternate settings for this interface,
  185.      * stored in no particular order */
  186.     struct usb_host_interface altsetting[0];
  187. };
  188. #define    ref_to_usb_interface_cache(r) \
  189.         container_of(r, struct usb_interface_cache, ref)
  190. #define    altsetting_to_usb_interface_cache(a) \
  191.         container_of(a, struct usb_interface_cache, altsetting[0])
  192.  
  193. /**
  194.  * struct usb_host_config - representation of a device's configuration
  195.  * @desc: the device's configuration descriptor.
  196.  * @string: pointer to the cached version of the iConfiguration string, if
  197.  *    present for this configuration.
  198.  * @interface: array of pointers to usb_interface structures, one for each
  199.  *    interface in the configuration.  The number of interfaces is stored
  200.  *    in desc.bNumInterfaces.  These pointers are valid only while the
  201.  *    the configuration is active.
  202.  * @intf_cache: array of pointers to usb_interface_cache structures, one
  203.  *    for each interface in the configuration.  These structures exist
  204.  *    for the entire life of the device.
  205.  * @extra: pointer to buffer containing all extra descriptors associated
  206.  *    with this configuration (those preceding the first interface
  207.  *    descriptor).
  208.  * @extralen: length of the extra descriptors buffer.
  209.  *
  210.  * USB devices may have multiple configurations, but only one can be active
  211.  * at any time.  Each encapsulates a different operational environment;
  212.  * for example, a dual-speed device would have separate configurations for
  213.  * full-speed and high-speed operation.  The number of configurations
  214.  * available is stored in the device descriptor as bNumConfigurations.
  215.  *
  216.  * A configuration can contain multiple interfaces.  Each corresponds to
  217.  * a different function of the USB device, and all are available whenever
  218.  * the configuration is active.  The USB standard says that interfaces
  219.  * are supposed to be numbered from 0 to desc.bNumInterfaces-1, but a lot
  220.  * of devices get this wrong.  In addition, the interface array is not
  221.  * guaranteed to be sorted in numerical order.  Use usb_ifnum_to_if() to
  222.  * look up an interface entry based on its number.
  223.  *
  224.  * Device drivers should not attempt to activate configurations.  The choice
  225.  * of which configuration to install is a policy decision based on such
  226.  * considerations as available power, functionality provided, and the user's
  227.  * desires (expressed through userspace tools).  However, drivers can call
  228.  * usb_reset_configuration() to reinitialize the current configuration and
  229.  * all its interfaces.
  230.  */
  231. struct usb_host_config {
  232.     struct usb_config_descriptor    desc;
  233.  
  234.     char *string;        /* iConfiguration string, if present */
  235.     /* the interfaces associated with this configuration,
  236.      * stored in no particular order */
  237.     struct usb_interface *interface[USB_MAXINTERFACES];
  238.  
  239.     /* Interface information available even when this is not the
  240.      * active configuration */
  241.     struct usb_interface_cache *intf_cache[USB_MAXINTERFACES];
  242.  
  243.     unsigned char *extra;   /* Extra descriptors */
  244.     int extralen;
  245. };
  246.  
  247. int __usb_get_extra_descriptor(char *buffer, unsigned size,
  248.     unsigned char type, void **ptr);
  249. #define usb_get_extra_descriptor(ifpoint,type,ptr)\
  250.     __usb_get_extra_descriptor((ifpoint)->extra,(ifpoint)->extralen,\
  251.         type,(void**)ptr)
  252.  
  253. /* ----------------------------------------------------------------------- */
  254.  
  255. struct usb_operations;
  256.  
  257. /* USB device number allocation bitmap */
  258. struct usb_devmap {
  259.     unsigned long devicemap[128 / (8*sizeof(unsigned long))];
  260. };
  261.  
  262. /*
  263.  * Allocated per bus (tree of devices) we have:
  264.  */
  265. struct usb_bus {
  266.     struct device *controller;    /* host/master side hardware */
  267.     int busnum;            /* Bus number (in order of reg) */
  268.     char *bus_name;            /* stable id (PCI slot_name etc) */
  269.     u8 otg_port;            /* 0, or number of OTG/HNP port */
  270.     unsigned is_b_host:1;        /* true during some HNP roleswitches */
  271.     unsigned b_hnp_enable:1;    /* OTG: did A-Host enable HNP? */
  272.  
  273.     int devnum_next;        /* Next open device number in
  274.                      * round-robin allocation */
  275.  
  276.     struct usb_devmap devmap;    /* device address allocation map */
  277.     struct usb_operations *op;    /* Operations (specific to the HC) */
  278.     struct usb_device *root_hub;    /* Root hub */
  279.     struct list_head bus_list;    /* list of busses */
  280.     void *hcpriv;                   /* Host Controller private data */
  281.  
  282.     int bandwidth_allocated;    /* on this bus: how much of the time
  283.                      * reserved for periodic (intr/iso)
  284.                      * requests is used, on average?
  285.                      * Units: microseconds/frame.
  286.                      * Limits: Full/low speed reserve 90%,
  287.                      * while high speed reserves 80%.
  288.                      */
  289.     int bandwidth_int_reqs;        /* number of Interrupt requests */
  290.     int bandwidth_isoc_reqs;    /* number of Isoc. requests */
  291.  
  292.     struct dentry *usbfs_dentry;    /* usbfs dentry entry for the bus */
  293.  
  294.     struct class_device *class_dev;    /* class device for this bus */
  295.     struct kref kref;        /* reference counting for this bus */
  296.     void (*release)(struct usb_bus *bus);
  297.  
  298. #if defined(CONFIG_USB_MON)
  299.     struct mon_bus *mon_bus;    /* non-null when associated */
  300.     int monitored;            /* non-zero when monitored */
  301. #endif
  302. };
  303.  
  304. /* ----------------------------------------------------------------------- */
  305.  
  306. /* This is arbitrary.
  307.  * From USB 2.0 spec Table 11-13, offset 7, a hub can
  308.  * have up to 255 ports. The most yet reported is 10.
  309.  */
  310. #define USB_MAXCHILDREN        (16)
  311.  
  312. struct usb_tt;
  313.  
  314. /*
  315.  * struct usb_device - kernel's representation of a USB device
  316.  *
  317.  * FIXME: Write the kerneldoc!
  318.  *
  319.  * Usbcore drivers should not set usbdev->state directly.  Instead use
  320.  * usb_set_device_state().
  321.  */
  322. struct usb_device {
  323.     int        devnum;        /* Address on USB bus */
  324.     char        devpath [16];    /* Use in messages: /port/port/... */
  325.     enum usb_device_state    state;    /* configured, not attached, etc */
  326.     enum usb_device_speed    speed;    /* high/full/low (or error) */
  327.  
  328.     struct usb_tt    *tt;         /* low/full speed dev, highspeed hub */
  329.     int        ttport;        /* device port on that tt hub */
  330.  
  331.     unsigned int toggle[2];        /* one bit for each endpoint
  332.                      * ([0] = IN, [1] = OUT) */
  333.  
  334.     struct usb_device *parent;    /* our hub, unless we're the root */
  335.     struct usb_bus *bus;        /* Bus we're part of */
  336.     struct usb_host_endpoint ep0;
  337.  
  338.     struct device dev;        /* Generic device interface */
  339.  
  340.     struct usb_device_descriptor descriptor;/* Descriptor */
  341.     struct usb_host_config *config;    /* All of the configs */
  342.  
  343.     struct usb_host_config *actconfig;/* the active configuration */
  344.     struct usb_host_endpoint *ep_in[16];
  345.     struct usb_host_endpoint *ep_out[16];
  346.  
  347.     char **rawdescriptors;        /* Raw descriptors for each config */
  348.  
  349.     unsigned short bus_mA;        /* Current available from the bus */
  350.     u8 portnum;            /* Parent port number (origin 1) */
  351.  
  352.     int have_langid;        /* whether string_langid is valid */
  353.     int string_langid;        /* language ID for strings */
  354.  
  355.     /* static strings from the device */
  356.     char *product;            /* iProduct string, if present */
  357.     char *manufacturer;        /* iManufacturer string, if present */
  358.     char *serial;            /* iSerialNumber string, if present */
  359.  
  360.     struct list_head filelist;
  361.     struct class_device *class_dev;
  362.     struct dentry *usbfs_dentry;    /* usbfs dentry entry for the device */
  363.  
  364.     /*
  365.      * Child devices - these can be either new devices
  366.      * (if this is a hub device), or different instances
  367.      * of this same device.
  368.      *
  369.      * Each instance needs its own set of data structures.
  370.      */
  371.  
  372.     int maxchild;            /* Number of ports if hub */
  373.     struct usb_device *children[USB_MAXCHILDREN];
  374. };
  375. #define    to_usb_device(d) container_of(d, struct usb_device, dev)
  376.  
  377. extern struct usb_device *usb_get_dev(struct usb_device *dev);
  378. extern void usb_put_dev(struct usb_device *dev);
  379.  
  380. /* USB device locking */
  381. #define usb_lock_device(udev)        down(&(udev)->dev.sem)
  382. #define usb_unlock_device(udev)        up(&(udev)->dev.sem)
  383. #define usb_trylock_device(udev)    down_trylock(&(udev)->dev.sem)
  384. extern int usb_lock_device_for_reset(struct usb_device *udev,
  385.         struct usb_interface *iface);
  386.  
  387. /* USB port reset for device reinitialization */
  388. extern int usb_reset_device(struct usb_device *dev);
  389.  
  390. extern struct usb_device *usb_find_device(u16 vendor_id, u16 product_id);
  391.  
  392. /*-------------------------------------------------------------------------*/
  393.  
  394. /* for drivers using iso endpoints */
  395. extern int usb_get_current_frame_number (struct usb_device *usb_dev);
  396.  
  397. /* used these for multi-interface device registration */
  398. extern int usb_driver_claim_interface(struct usb_driver *driver,
  399.             struct usb_interface *iface, void* priv);
  400.  
  401. /**
  402.  * usb_interface_claimed - returns true iff an interface is claimed
  403.  * @iface: the interface being checked
  404.  *
  405.  * Returns true (nonzero) iff the interface is claimed, else false (zero).
  406.  * Callers must own the driver model's usb bus readlock.  So driver
  407.  * probe() entries don't need extra locking, but other call contexts
  408.  * may need to explicitly claim that lock.
  409.  *
  410.  */
  411. static inline int usb_interface_claimed(struct usb_interface *iface) {
  412.     return (iface->dev.driver != NULL);
  413. }
  414.  
  415. extern void usb_driver_release_interface(struct usb_driver *driver,
  416.             struct usb_interface *iface);
  417. const struct usb_device_id *usb_match_id(struct usb_interface *interface,
  418.                      const struct usb_device_id *id);
  419.  
  420. extern struct usb_interface *usb_find_interface(struct usb_driver *drv,
  421.         int minor);
  422. extern struct usb_interface *usb_ifnum_to_if(struct usb_device *dev,
  423.         unsigned ifnum);
  424. extern struct usb_host_interface *usb_altnum_to_altsetting(
  425.         struct usb_interface *intf, unsigned int altnum);
  426.  
  427.  
  428. /**
  429.  * usb_make_path - returns stable device path in the usb tree
  430.  * @dev: the device whose path is being constructed
  431.  * @buf: where to put the string
  432.  * @size: how big is "buf"?
  433.  *
  434.  * Returns length of the string (> 0) or negative if size was too small.
  435.  *
  436.  * This identifier is intended to be "stable", reflecting physical paths in
  437.  * hardware such as physical bus addresses for host controllers or ports on
  438.  * USB hubs.  That makes it stay the same until systems are physically
  439.  * reconfigured, by re-cabling a tree of USB devices or by moving USB host
  440.  * controllers.  Adding and removing devices, including virtual root hubs
  441.  * in host controller driver modules, does not change these path identifers;
  442.  * neither does rebooting or re-enumerating.  These are more useful identifiers
  443.  * than changeable ("unstable") ones like bus numbers or device addresses.
  444.  *
  445.  * With a partial exception for devices connected to USB 2.0 root hubs, these
  446.  * identifiers are also predictable.  So long as the device tree isn't changed,
  447.  * plugging any USB device into a given hub port always gives it the same path.
  448.  * Because of the use of "companion" controllers, devices connected to ports on
  449.  * USB 2.0 root hubs (EHCI host controllers) will get one path ID if they are
  450.  * high speed, and a different one if they are full or low speed.
  451.  */
  452. static inline int usb_make_path (struct usb_device *dev, char *buf,
  453.         size_t size)
  454. {
  455.     int actual;
  456.     actual = snprintf (buf, size, "usb-%s-%s", dev->bus->bus_name,
  457.             dev->devpath);
  458.     return (actual >= (int)size) ? -1 : actual;
  459. }
  460.  
  461. /*-------------------------------------------------------------------------*/
  462.  
  463. #define USB_DEVICE_ID_MATCH_DEVICE \
  464.         (USB_DEVICE_ID_MATCH_VENDOR | USB_DEVICE_ID_MATCH_PRODUCT)
  465. #define USB_DEVICE_ID_MATCH_DEV_RANGE \
  466.         (USB_DEVICE_ID_MATCH_DEV_LO | USB_DEVICE_ID_MATCH_DEV_HI)
  467. #define USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION \
  468.         (USB_DEVICE_ID_MATCH_DEVICE | USB_DEVICE_ID_MATCH_DEV_RANGE)
  469. #define USB_DEVICE_ID_MATCH_DEV_INFO \
  470.         (USB_DEVICE_ID_MATCH_DEV_CLASS | \
  471.         USB_DEVICE_ID_MATCH_DEV_SUBCLASS | \
  472.         USB_DEVICE_ID_MATCH_DEV_PROTOCOL)
  473. #define USB_DEVICE_ID_MATCH_INT_INFO \
  474.         (USB_DEVICE_ID_MATCH_INT_CLASS | \
  475.         USB_DEVICE_ID_MATCH_INT_SUBCLASS | \
  476.         USB_DEVICE_ID_MATCH_INT_PROTOCOL)
  477.  
  478. /**
  479.  * USB_DEVICE - macro used to describe a specific usb device
  480.  * @vend: the 16 bit USB Vendor ID
  481.  * @prod: the 16 bit USB Product ID
  482.  *
  483.  * This macro is used to create a struct usb_device_id that matches a
  484.  * specific device.
  485.  */
  486. #define USB_DEVICE(vend,prod) \
  487.     .match_flags = USB_DEVICE_ID_MATCH_DEVICE, .idVendor = (vend), \
  488.             .idProduct = (prod)
  489. /**
  490.  * USB_DEVICE_VER - macro used to describe a specific usb device with a
  491.  *        version range
  492.  * @vend: the 16 bit USB Vendor ID
  493.  * @prod: the 16 bit USB Product ID
  494.  * @lo: the bcdDevice_lo value
  495.  * @hi: the bcdDevice_hi value
  496.  *
  497.  * This macro is used to create a struct usb_device_id that matches a
  498.  * specific device, with a version range.
  499.  */
  500. #define USB_DEVICE_VER(vend,prod,lo,hi) \
  501.     .match_flags = USB_DEVICE_ID_MATCH_DEVICE_AND_VERSION, \
  502.     .idVendor = (vend), .idProduct = (prod), \
  503.     .bcdDevice_lo = (lo), .bcdDevice_hi = (hi)
  504.  
  505. /**
  506.  * USB_DEVICE_INFO - macro used to describe a class of usb devices
  507.  * @cl: bDeviceClass value
  508.  * @sc: bDeviceSubClass value
  509.  * @pr: bDeviceProtocol value
  510.  *
  511.  * This macro is used to create a struct usb_device_id that matches a
  512.  * specific class of devices.
  513.  */
  514. #define USB_DEVICE_INFO(cl,sc,pr) \
  515.     .match_flags = USB_DEVICE_ID_MATCH_DEV_INFO, .bDeviceClass = (cl), \
  516.     .bDeviceSubClass = (sc), .bDeviceProtocol = (pr)
  517.  
  518. /**
  519.  * USB_INTERFACE_INFO - macro used to describe a class of usb interfaces 
  520.  * @cl: bInterfaceClass value
  521.  * @sc: bInterfaceSubClass value
  522.  * @pr: bInterfaceProtocol value
  523.  *
  524.  * This macro is used to create a struct usb_device_id that matches a
  525.  * specific class of interfaces.
  526.  */
  527. #define USB_INTERFACE_INFO(cl,sc,pr) \
  528.     .match_flags = USB_DEVICE_ID_MATCH_INT_INFO, .bInterfaceClass = (cl), \
  529.     .bInterfaceSubClass = (sc), .bInterfaceProtocol = (pr)
  530.  
  531. /* ----------------------------------------------------------------------- */
  532.  
  533. struct usb_dynids {
  534.     spinlock_t lock;
  535.     struct list_head list;
  536. };
  537.  
  538. /**
  539.  * struct usb_driver - identifies USB driver to usbcore
  540.  * @name: The driver name should be unique among USB drivers,
  541.  *    and should normally be the same as the module name.
  542.  * @probe: Called to see if the driver is willing to manage a particular
  543.  *    interface on a device.  If it is, probe returns zero and uses
  544.  *    dev_set_drvdata() to associate driver-specific data with the
  545.  *    interface.  It may also use usb_set_interface() to specify the
  546.  *    appropriate altsetting.  If unwilling to manage the interface,
  547.  *    return a negative errno value.
  548.  * @disconnect: Called when the interface is no longer accessible, usually
  549.  *    because its device has been (or is being) disconnected or the
  550.  *    driver module is being unloaded.
  551.  * @ioctl: Used for drivers that want to talk to userspace through
  552.  *    the "usbfs" filesystem.  This lets devices provide ways to
  553.  *    expose information to user space regardless of where they
  554.  *    do (or don't) show up otherwise in the filesystem.
  555.  * @suspend: Called when the device is going to be suspended by the system.
  556.  * @resume: Called when the device is being resumed by the system.
  557.  * @id_table: USB drivers use ID table to support hotplugging.
  558.  *    Export this with MODULE_DEVICE_TABLE(usb,...).  This must be set
  559.  *    or your driver's probe function will never get called.
  560.  * @dynids: used internally to hold the list of dynamically added device
  561.  *    ids for this driver.
  562.  * @driver: the driver model core driver structure.
  563.  * @no_dynamic_id: if set to 1, the USB core will not allow dynamic ids to be
  564.  *    added to this driver by preventing the sysfs file from being created.
  565.  *
  566.  * USB drivers must provide a name, probe() and disconnect() methods,
  567.  * and an id_table.  Other driver fields are optional.
  568.  *
  569.  * The id_table is used in hotplugging.  It holds a set of descriptors,
  570.  * and specialized data may be associated with each entry.  That table
  571.  * is used by both user and kernel mode hotplugging support.
  572.  *
  573.  * The probe() and disconnect() methods are called in a context where
  574.  * they can sleep, but they should avoid abusing the privilege.  Most
  575.  * work to connect to a device should be done when the device is opened,
  576.  * and undone at the last close.  The disconnect code needs to address
  577.  * concurrency issues with respect to open() and close() methods, as
  578.  * well as forcing all pending I/O requests to complete (by unlinking
  579.  * them as necessary, and blocking until the unlinks complete).
  580.  */
  581. struct usb_driver {
  582.     const char *name;
  583.  
  584.     int (*probe) (struct usb_interface *intf,
  585.               const struct usb_device_id *id);
  586.  
  587.     void (*disconnect) (struct usb_interface *intf);
  588.  
  589.     int (*ioctl) (struct usb_interface *intf, unsigned int code,
  590.             void *buf);
  591.  
  592.     int (*suspend) (struct usb_interface *intf, pm_message_t message);
  593.     int (*resume) (struct usb_interface *intf);
  594.  
  595.     const struct usb_device_id *id_table;
  596.  
  597.     struct usb_dynids dynids;
  598.     struct device_driver driver;
  599.     unsigned int no_dynamic_id:1;
  600. };
  601. #define    to_usb_driver(d) container_of(d, struct usb_driver, driver)
  602.  
  603. extern struct bus_type usb_bus_type;
  604.  
  605. /**
  606.  * struct usb_class_driver - identifies a USB driver that wants to use the USB major number
  607.  * @name: the usb class device name for this driver.  Will show up in sysfs.
  608.  * @fops: pointer to the struct file_operations of this driver.
  609.  * @minor_base: the start of the minor range for this driver.
  610.  *
  611.  * This structure is used for the usb_register_dev() and
  612.  * usb_unregister_dev() functions, to consolidate a number of the
  613.  * parameters used for them.
  614.  */
  615. struct usb_class_driver {
  616.     char *name;
  617.     const struct file_operations *fops;
  618.     int minor_base;
  619. };
  620.  
  621. /*
  622.  * use these in module_init()/module_exit()
  623.  * and don't forget MODULE_DEVICE_TABLE(usb, ...)
  624.  */
  625. int usb_register_driver(struct usb_driver *, struct module *);
  626. static inline int usb_register(struct usb_driver *driver)
  627. {
  628.     return usb_register_driver(driver, THIS_MODULE);
  629. }
  630. extern void usb_deregister(struct usb_driver *);
  631.  
  632. extern int usb_register_dev(struct usb_interface *intf,
  633.                 struct usb_class_driver *class_driver);
  634. extern void usb_deregister_dev(struct usb_interface *intf,
  635.                    struct usb_class_driver *class_driver);
  636.  
  637. extern int usb_disabled(void);
  638.  
  639. /* ----------------------------------------------------------------------- */
  640.  
  641. /*
  642.  * URB support, for asynchronous request completions
  643.  */
  644.  
  645. /*
  646.  * urb->transfer_flags:
  647.  */
  648. #define URB_SHORT_NOT_OK    0x0001    /* report short reads as errors */
  649. #define URB_ISO_ASAP        0x0002    /* iso-only, urb->start_frame
  650.                      * ignored */
  651. #define URB_NO_TRANSFER_DMA_MAP    0x0004    /* urb->transfer_dma valid on submit */
  652. #define URB_NO_SETUP_DMA_MAP    0x0008    /* urb->setup_dma valid on submit */
  653. #define URB_NO_FSBR        0x0020    /* UHCI-specific */
  654. #define URB_ZERO_PACKET        0x0040    /* Finish bulk OUT with short packet */
  655. #define URB_NO_INTERRUPT    0x0080    /* HINT: no non-error interrupt
  656.                      * needed */
  657.  
  658. struct usb_iso_packet_descriptor {
  659.     unsigned int offset;
  660.     unsigned int length;        /* expected length */
  661.     unsigned int actual_length;
  662.     unsigned int status;
  663. };
  664.  
  665. struct urb;
  666. struct pt_regs;
  667.  
  668. typedef void (*usb_complete_t)(struct urb *, struct pt_regs *);
  669.  
  670. /**
  671.  * struct urb - USB Request Block
  672.  * @urb_list: For use by current owner of the URB.
  673.  * @pipe: Holds endpoint number, direction, type, and more.
  674.  *    Create these values with the eight macros available;
  675.  *    usb_{snd,rcv}TYPEpipe(dev,endpoint), where the TYPE is "ctrl"
  676.  *    (control), "bulk", "int" (interrupt), or "iso" (isochronous).
  677.  *    For example usb_sndbulkpipe() or usb_rcvintpipe().  Endpoint
  678.  *    numbers range from zero to fifteen.  Note that "in" endpoint two
  679.  *    is a different endpoint (and pipe) from "out" endpoint two.
  680.  *    The current configuration controls the existence, type, and
  681.  *    maximum packet size of any given endpoint.
  682.  * @dev: Identifies the USB device to perform the request.
  683.  * @status: This is read in non-iso completion functions to get the
  684.  *    status of the particular request.  ISO requests only use it
  685.  *    to tell whether the URB was unlinked; detailed status for
  686.  *    each frame is in the fields of the iso_frame-desc.
  687.  * @transfer_flags: A variety of flags may be used to affect how URB
  688.  *    submission, unlinking, or operation are handled.  Different
  689.  *    kinds of URB can use different flags.
  690.  * @transfer_buffer:  This identifies the buffer to (or from) which
  691.  *     the I/O request will be performed (unless URB_NO_TRANSFER_DMA_MAP
  692.  *    is set).  This buffer must be suitable for DMA; allocate it with
  693.  *    kmalloc() or equivalent.  For transfers to "in" endpoints, contents
  694.  *    of this buffer will be modified.  This buffer is used for the data
  695.  *    stage of control transfers.
  696.  * @transfer_dma: When transfer_flags includes URB_NO_TRANSFER_DMA_MAP,
  697.  *    the device driver is saying that it provided this DMA address,
  698.  *    which the host controller driver should use in preference to the
  699.  *    transfer_buffer.
  700.  * @transfer_buffer_length: How big is transfer_buffer.  The transfer may
  701.  *    be broken up into chunks according to the current maximum packet
  702.  *    size for the endpoint, which is a function of the configuration
  703.  *    and is encoded in the pipe.  When the length is zero, neither
  704.  *    transfer_buffer nor transfer_dma is used.
  705.  * @actual_length: This is read in non-iso completion functions, and
  706.  *    it tells how many bytes (out of transfer_buffer_length) were
  707.  *    transferred.  It will normally be the same as requested, unless
  708.  *    either an error was reported or a short read was performed.
  709.  *    The URB_SHORT_NOT_OK transfer flag may be used to make such
  710.  *    short reads be reported as errors. 
  711.  * @setup_packet: Only used for control transfers, this points to eight bytes
  712.  *    of setup data.  Control transfers always start by sending this data
  713.  *    to the device.  Then transfer_buffer is read or written, if needed.
  714.  * @setup_dma: For control transfers with URB_NO_SETUP_DMA_MAP set, the
  715.  *    device driver has provided this DMA address for the setup packet.
  716.  *    The host controller driver should use this in preference to
  717.  *    setup_packet.
  718.  * @start_frame: Returns the initial frame for isochronous transfers.
  719.  * @number_of_packets: Lists the number of ISO transfer buffers.
  720.  * @interval: Specifies the polling interval for interrupt or isochronous
  721.  *    transfers.  The units are frames (milliseconds) for for full and low
  722.  *    speed devices, and microframes (1/8 millisecond) for highspeed ones.
  723.  * @error_count: Returns the number of ISO transfers that reported errors.
  724.  * @context: For use in completion functions.  This normally points to
  725.  *    request-specific driver context.
  726.  * @complete: Completion handler. This URB is passed as the parameter to the
  727.  *    completion function.  The completion function may then do what
  728.  *    it likes with the URB, including resubmitting or freeing it.
  729.  * @iso_frame_desc: Used to provide arrays of ISO transfer buffers and to 
  730.  *    collect the transfer status for each buffer.
  731.  *
  732.  * This structure identifies USB transfer requests.  URBs must be allocated by
  733.  * calling usb_alloc_urb() and freed with a call to usb_free_urb().
  734.  * Initialization may be done using various usb_fill_*_urb() functions.  URBs
  735.  * are submitted using usb_submit_urb(), and pending requests may be canceled
  736.  * using usb_unlink_urb() or usb_kill_urb().
  737.  *
  738.  * Data Transfer Buffers:
  739.  *
  740.  * Normally drivers provide I/O buffers allocated with kmalloc() or otherwise
  741.  * taken from the general page pool.  That is provided by transfer_buffer
  742.  * (control requests also use setup_packet), and host controller drivers
  743.  * perform a dma mapping (and unmapping) for each buffer transferred.  Those
  744.  * mapping operations can be expensive on some platforms (perhaps using a dma
  745.  * bounce buffer or talking to an IOMMU),
  746.  * although they're cheap on commodity x86 and ppc hardware.
  747.  *
  748.  * Alternatively, drivers may pass the URB_NO_xxx_DMA_MAP transfer flags,
  749.  * which tell the host controller driver that no such mapping is needed since
  750.  * the device driver is DMA-aware.  For example, a device driver might
  751.  * allocate a DMA buffer with usb_buffer_alloc() or call usb_buffer_map().
  752.  * When these transfer flags are provided, host controller drivers will
  753.  * attempt to use the dma addresses found in the transfer_dma and/or
  754.  * setup_dma fields rather than determining a dma address themselves.  (Note
  755.  * that transfer_buffer and setup_packet must still be set because not all
  756.  * host controllers use DMA, nor do virtual root hubs).
  757.  *
  758.  * Initialization:
  759.  *
  760.  * All URBs submitted must initialize the dev, pipe, transfer_flags (may be
  761.  * zero), and complete fields.  All URBs must also initialize
  762.  * transfer_buffer and transfer_buffer_length.  They may provide the
  763.  * URB_SHORT_NOT_OK transfer flag, indicating that short reads are
  764.  * to be treated as errors; that flag is invalid for write requests.
  765.  *
  766.  * Bulk URBs may
  767.  * use the URB_ZERO_PACKET transfer flag, indicating that bulk OUT transfers
  768.  * should always terminate with a short packet, even if it means adding an
  769.  * extra zero length packet.
  770.  *
  771.  * Control URBs must provide a setup_packet.  The setup_packet and
  772.  * transfer_buffer may each be mapped for DMA or not, independently of
  773.  * the other.  The transfer_flags bits URB_NO_TRANSFER_DMA_MAP and
  774.  * URB_NO_SETUP_DMA_MAP indicate which buffers have already been mapped.
  775.  * URB_NO_SETUP_DMA_MAP is ignored for non-control URBs.
  776.  *
  777.  * Interrupt URBs must provide an interval, saying how often (in milliseconds
  778.  * or, for highspeed devices, 125 microsecond units)
  779.  * to poll for transfers.  After the URB has been submitted, the interval
  780.  * field reflects how the transfer was actually scheduled.
  781.  * The polling interval may be more frequent than requested.
  782.  * For example, some controllers have a maximum interval of 32 milliseconds,
  783.  * while others support intervals of up to 1024 milliseconds.
  784.  * Isochronous URBs also have transfer intervals.  (Note that for isochronous
  785.  * endpoints, as well as high speed interrupt endpoints, the encoding of
  786.  * the transfer interval in the endpoint descriptor is logarithmic.
  787.  * Device drivers must convert that value to linear units themselves.)
  788.  *
  789.  * Isochronous URBs normally use the URB_ISO_ASAP transfer flag, telling
  790.  * the host controller to schedule the transfer as soon as bandwidth
  791.  * utilization allows, and then set start_frame to reflect the actual frame
  792.  * selected during submission.  Otherwise drivers must specify the start_frame
  793.  * and handle the case where the transfer can't begin then.  However, drivers
  794.  * won't know how bandwidth is currently allocated, and while they can
  795.  * find the current frame using usb_get_current_frame_number () they can't
  796.  * know the range for that frame number.  (Ranges for frame counter values
  797.  * are HC-specific, and can go from 256 to 65536 frames from "now".)
  798.  *
  799.  * Isochronous URBs have a different data transfer model, in part because
  800.  * the quality of service is only "best effort".  Callers provide specially
  801.  * allocated URBs, with number_of_packets worth of iso_frame_desc structures
  802.  * at the end.  Each such packet is an individual ISO transfer.  Isochronous
  803.  * URBs are normally queued, submitted by drivers to arrange that
  804.  * transfers are at least double buffered, and then explicitly resubmitted
  805.  * in completion handlers, so
  806.  * that data (such as audio or video) streams at as constant a rate as the
  807.  * host controller scheduler can support.
  808.  *
  809.  * Completion Callbacks:
  810.  *
  811.  * The completion callback is made in_interrupt(), and one of the first
  812.  * things that a completion handler should do is check the status field.
  813.  * The status field is provided for all URBs.  It is used to report
  814.  * unlinked URBs, and status for all non-ISO transfers.  It should not
  815.  * be examined before the URB is returned to the completion handler.
  816.  *
  817.  * The context field is normally used to link URBs back to the relevant
  818.  * driver or request state.
  819.  *
  820.  * When the completion callback is invoked for non-isochronous URBs, the
  821.  * actual_length field tells how many bytes were transferred.  This field
  822.  * is updated even when the URB terminated with an error or was unlinked.
  823.  *
  824.  * ISO transfer status is reported in the status and actual_length fields
  825.  * of the iso_frame_desc array, and the number of errors is reported in
  826.  * error_count.  Completion callbacks for ISO transfers will normally
  827.  * (re)submit URBs to ensure a constant transfer rate.
  828.  *
  829.  * Note that even fields marked "public" should not be touched by the driver
  830.  * when the urb is owned by the hcd, that is, since the call to
  831.  * usb_submit_urb() till the entry into the completion routine.
  832.  */
  833. struct urb
  834. {
  835.     /* private: usb core and host controller only fields in the urb */
  836.     struct kref kref;        /* reference count of the URB */
  837.     spinlock_t lock;        /* lock for the URB */
  838.     void *hcpriv;            /* private data for host controller */
  839.     int bandwidth;            /* bandwidth for INT/ISO request */
  840.     atomic_t use_count;        /* concurrent submissions counter */
  841.     u8 reject;            /* submissions will fail */
  842.  
  843.     /* public: documented fields in the urb that can be used by drivers */
  844.     struct list_head urb_list;    /* list head for use by the urb's
  845.                      * current owner */
  846.     struct usb_device *dev;     /* (in) pointer to associated device */
  847.     unsigned int pipe;        /* (in) pipe information */
  848.     int status;            /* (return) non-ISO status */
  849.     unsigned int transfer_flags;    /* (in) URB_SHORT_NOT_OK | ...*/
  850.     void *transfer_buffer;        /* (in) associated data buffer */
  851.     dma_addr_t transfer_dma;    /* (in) dma addr for transfer_buffer */
  852.     int transfer_buffer_length;    /* (in) data buffer length */
  853.     int actual_length;        /* (return) actual transfer length */
  854.     unsigned char *setup_packet;    /* (in) setup packet (control only) */
  855.     dma_addr_t setup_dma;        /* (in) dma addr for setup_packet */
  856.     int start_frame;        /* (modify) start frame (ISO) */
  857.     int number_of_packets;        /* (in) number of ISO packets */
  858.     int interval;            /* (modify) transfer interval
  859.                      * (INT/ISO) */
  860.     int error_count;        /* (return) number of ISO errors */
  861.     void *context;            /* (in) context for completion */
  862.     usb_complete_t complete;    /* (in) completion routine */
  863.     struct usb_iso_packet_descriptor iso_frame_desc[0];
  864.                     /* (in) ISO ONLY */
  865. };
  866.  
  867. /* ----------------------------------------------------------------------- */
  868.  
  869. /**
  870.  * usb_fill_control_urb - initializes a control urb
  871.  * @urb: pointer to the urb to initialize.
  872.  * @dev: pointer to the struct usb_device for this urb.
  873.  * @pipe: the endpoint pipe
  874.  * @setup_packet: pointer to the setup_packet buffer
  875.  * @transfer_buffer: pointer to the transfer buffer
  876.  * @buffer_length: length of the transfer buffer
  877.  * @complete: pointer to the usb_complete_t function
  878.  * @context: what to set the urb context to.
  879.  *
  880.  * Initializes a control urb with the proper information needed to submit
  881.  * it to a device.
  882.  */
  883. static inline void usb_fill_control_urb (struct urb *urb,
  884.                      struct usb_device *dev,
  885.                      unsigned int pipe,
  886.                      unsigned char *setup_packet,
  887.                      void *transfer_buffer,
  888.                      int buffer_length,
  889.                      usb_complete_t complete,
  890.                      void *context)
  891. {
  892.     spin_lock_init(&urb->lock);
  893.     urb->dev = dev;
  894.     urb->pipe = pipe;
  895.     urb->setup_packet = setup_packet;
  896.     urb->transfer_buffer = transfer_buffer;
  897.     urb->transfer_buffer_length = buffer_length;
  898.     urb->complete = complete;
  899.     urb->context = context;
  900. }
  901.  
  902. /**
  903.  * usb_fill_bulk_urb - macro to help initialize a bulk urb
  904.  * @urb: pointer to the urb to initialize.
  905.  * @dev: pointer to the struct usb_device for this urb.
  906.  * @pipe: the endpoint pipe
  907.  * @transfer_buffer: pointer to the transfer buffer
  908.  * @buffer_length: length of the transfer buffer
  909.  * @complete: pointer to the usb_complete_t function
  910.  * @context: what to set the urb context to.
  911.  *
  912.  * Initializes a bulk urb with the proper information needed to submit it
  913.  * to a device.
  914.  */
  915. static inline void usb_fill_bulk_urb (struct urb *urb,
  916.                       struct usb_device *dev,
  917.                       unsigned int pipe,
  918.                       void *transfer_buffer,
  919.                       int buffer_length,
  920.                       usb_complete_t complete,
  921.                       void *context)
  922. {
  923.     spin_lock_init(&urb->lock);
  924.     urb->dev = dev;
  925.     urb->pipe = pipe;
  926.     urb->transfer_buffer = transfer_buffer;
  927.     urb->transfer_buffer_length = buffer_length;
  928.     urb->complete = complete;
  929.     urb->context = context;
  930. }
  931.  
  932. /**
  933.  * usb_fill_int_urb - macro to help initialize a interrupt urb
  934.  * @urb: pointer to the urb to initialize.
  935.  * @dev: pointer to the struct usb_device for this urb.
  936.  * @pipe: the endpoint pipe
  937.  * @transfer_buffer: pointer to the transfer buffer
  938.  * @buffer_length: length of the transfer buffer
  939.  * @complete: pointer to the usb_complete_t function
  940.  * @context: what to set the urb context to.
  941.  * @interval: what to set the urb interval to, encoded like
  942.  *    the endpoint descriptor's bInterval value.
  943.  *
  944.  * Initializes a interrupt urb with the proper information needed to submit
  945.  * it to a device.
  946.  * Note that high speed interrupt endpoints use a logarithmic encoding of
  947.  * the endpoint interval, and express polling intervals in microframes
  948.  * (eight per millisecond) rather than in frames (one per millisecond).
  949.  */
  950. static inline void usb_fill_int_urb (struct urb *urb,
  951.                      struct usb_device *dev,
  952.                      unsigned int pipe,
  953.                      void *transfer_buffer,
  954.                      int buffer_length,
  955.                      usb_complete_t complete,
  956.                      void *context,
  957.                      int interval)
  958. {
  959.     spin_lock_init(&urb->lock);
  960.     urb->dev = dev;
  961.     urb->pipe = pipe;
  962.     urb->transfer_buffer = transfer_buffer;
  963.     urb->transfer_buffer_length = buffer_length;
  964.     urb->complete = complete;
  965.     urb->context = context;
  966.     if (dev->speed == USB_SPEED_HIGH)
  967.         urb->interval = 1 << (interval - 1);
  968.     else
  969.         urb->interval = interval;
  970.     urb->start_frame = -1;
  971. }
  972.  
  973. extern void usb_init_urb(struct urb *urb);
  974. extern struct urb *usb_alloc_urb(int iso_packets, gfp_t mem_flags);
  975. extern void usb_free_urb(struct urb *urb);
  976. #define usb_put_urb usb_free_urb
  977. extern struct urb *usb_get_urb(struct urb *urb);
  978. extern int usb_submit_urb(struct urb *urb, gfp_t mem_flags);
  979. extern int usb_unlink_urb(struct urb *urb);
  980. extern void usb_kill_urb(struct urb *urb);
  981.  
  982. #define HAVE_USB_BUFFERS
  983. void *usb_buffer_alloc (struct usb_device *dev, size_t size,
  984.     gfp_t mem_flags, dma_addr_t *dma);
  985. void usb_buffer_free (struct usb_device *dev, size_t size,
  986.     void *addr, dma_addr_t dma);
  987.  
  988. #if 0
  989. struct urb *usb_buffer_map (struct urb *urb);
  990. void usb_buffer_dmasync (struct urb *urb);
  991. void usb_buffer_unmap (struct urb *urb);
  992. #endif
  993.  
  994. struct scatterlist;
  995. int usb_buffer_map_sg (struct usb_device *dev, unsigned pipe,
  996.         struct scatterlist *sg, int nents);
  997. #if 0
  998. void usb_buffer_dmasync_sg (struct usb_device *dev, unsigned pipe,
  999.         struct scatterlist *sg, int n_hw_ents);
  1000. #endif
  1001. void usb_buffer_unmap_sg (struct usb_device *dev, unsigned pipe,
  1002.         struct scatterlist *sg, int n_hw_ents);
  1003.  
  1004. /*-------------------------------------------------------------------*
  1005.  *                         SYNCHRONOUS CALL SUPPORT                  *
  1006.  *-------------------------------------------------------------------*/
  1007.  
  1008. extern int usb_control_msg(struct usb_device *dev, unsigned int pipe,
  1009.     __u8 request, __u8 requesttype, __u16 value, __u16 index,
  1010.     void *data, __u16 size, int timeout);
  1011. extern int usb_bulk_msg(struct usb_device *usb_dev, unsigned int pipe,
  1012.     void *data, int len, int *actual_length,
  1013.     int timeout);
  1014.  
  1015. /* wrappers around usb_control_msg() for the most common standard requests */
  1016. extern int usb_get_descriptor(struct usb_device *dev, unsigned char desctype,
  1017.     unsigned char descindex, void *buf, int size);
  1018. extern int usb_get_status(struct usb_device *dev,
  1019.     int type, int target, void *data);
  1020. extern int usb_string(struct usb_device *dev, int index,
  1021.     char *buf, size_t size);
  1022.  
  1023. /* wrappers that also update important state inside usbcore */
  1024. extern int usb_clear_halt(struct usb_device *dev, int pipe);
  1025. extern int usb_reset_configuration(struct usb_device *dev);
  1026. extern int usb_set_interface(struct usb_device *dev, int ifnum, int alternate);
  1027.  
  1028. /*
  1029.  * timeouts, in milliseconds, used for sending/receiving control messages
  1030.  * they typically complete within a few frames (msec) after they're issued
  1031.  * USB identifies 5 second timeouts, maybe more in a few cases, and a few
  1032.  * slow devices (like some MGE Ellipse UPSes) actually push that limit.
  1033.  */
  1034. #define USB_CTRL_GET_TIMEOUT    5000
  1035. #define USB_CTRL_SET_TIMEOUT    5000
  1036.  
  1037.  
  1038. /**
  1039.  * struct usb_sg_request - support for scatter/gather I/O
  1040.  * @status: zero indicates success, else negative errno
  1041.  * @bytes: counts bytes transferred.
  1042.  *
  1043.  * These requests are initialized using usb_sg_init(), and then are used
  1044.  * as request handles passed to usb_sg_wait() or usb_sg_cancel().  Most
  1045.  * members of the request object aren't for driver access.
  1046.  *
  1047.  * The status and bytecount values are valid only after usb_sg_wait()
  1048.  * returns.  If the status is zero, then the bytecount matches the total
  1049.  * from the request.
  1050.  *
  1051.  * After an error completion, drivers may need to clear a halt condition
  1052.  * on the endpoint.
  1053.  */
  1054. struct usb_sg_request {
  1055.     int            status;
  1056.     size_t            bytes;
  1057.  
  1058.     /* 
  1059.      * members below are private: to usbcore,
  1060.      * and are not provided for driver access!
  1061.      */
  1062.     spinlock_t        lock;
  1063.  
  1064.     struct usb_device    *dev;
  1065.     int            pipe;
  1066.     struct scatterlist    *sg;
  1067.     int            nents;
  1068.  
  1069.     int            entries;
  1070.     struct urb        **urbs;
  1071.  
  1072.     int            count;
  1073.     struct completion    complete;
  1074. };
  1075.  
  1076. int usb_sg_init (
  1077.     struct usb_sg_request    *io,
  1078.     struct usb_device    *dev,
  1079.     unsigned        pipe, 
  1080.     unsigned        period,
  1081.     struct scatterlist    *sg,
  1082.     int            nents,
  1083.     size_t            length,
  1084.     gfp_t            mem_flags
  1085. );
  1086. void usb_sg_cancel (struct usb_sg_request *io);
  1087. void usb_sg_wait (struct usb_sg_request *io);
  1088.  
  1089.  
  1090. /* ----------------------------------------------------------------------- */
  1091.  
  1092. /*
  1093.  * For various legacy reasons, Linux has a small cookie that's paired with
  1094.  * a struct usb_device to identify an endpoint queue.  Queue characteristics
  1095.  * are defined by the endpoint's descriptor.  This cookie is called a "pipe",
  1096.  * an unsigned int encoded as:
  1097.  *
  1098.  *  - direction:    bit 7        (0 = Host-to-Device [Out],
  1099.  *                     1 = Device-to-Host [In] ...
  1100.  *                    like endpoint bEndpointAddress)
  1101.  *  - device address:    bits 8-14       ... bit positions known to uhci-hcd
  1102.  *  - endpoint:        bits 15-18      ... bit positions known to uhci-hcd
  1103.  *  - pipe type:    bits 30-31    (00 = isochronous, 01 = interrupt,
  1104.  *                     10 = control, 11 = bulk)
  1105.  *
  1106.  * Given the device address and endpoint descriptor, pipes are redundant.
  1107.  */
  1108.  
  1109. /* NOTE:  these are not the standard USB_ENDPOINT_XFER_* values!! */
  1110. /* (yet ... they're the values used by usbfs) */
  1111. #define PIPE_ISOCHRONOUS        0
  1112. #define PIPE_INTERRUPT            1
  1113. #define PIPE_CONTROL            2
  1114. #define PIPE_BULK            3
  1115.  
  1116. #define usb_pipein(pipe)    ((pipe) & USB_DIR_IN)
  1117. #define usb_pipeout(pipe)    (!usb_pipein(pipe))
  1118.  
  1119. #define usb_pipedevice(pipe)    (((pipe) >> 8) & 0x7f)
  1120. #define usb_pipeendpoint(pipe)    (((pipe) >> 15) & 0xf)
  1121.  
  1122. #define usb_pipetype(pipe)    (((pipe) >> 30) & 3)
  1123. #define usb_pipeisoc(pipe)    (usb_pipetype((pipe)) == PIPE_ISOCHRONOUS)
  1124. #define usb_pipeint(pipe)    (usb_pipetype((pipe)) == PIPE_INTERRUPT)
  1125. #define usb_pipecontrol(pipe)    (usb_pipetype((pipe)) == PIPE_CONTROL)
  1126. #define usb_pipebulk(pipe)    (usb_pipetype((pipe)) == PIPE_BULK)
  1127.  
  1128. /* The D0/D1 toggle bits ... USE WITH CAUTION (they're almost hcd-internal) */
  1129. #define usb_gettoggle(dev, ep, out) (((dev)->toggle[out] >> (ep)) & 1)
  1130. #define    usb_dotoggle(dev, ep, out)  ((dev)->toggle[out] ^= (1 << (ep)))
  1131. #define usb_settoggle(dev, ep, out, bit) \
  1132.         ((dev)->toggle[out] = ((dev)->toggle[out] & ~(1 << (ep))) | \
  1133.          ((bit) << (ep)))
  1134.  
  1135.  
  1136. static inline unsigned int __create_pipe(struct usb_device *dev,
  1137.         unsigned int endpoint)
  1138. {
  1139.     return (dev->devnum << 8) | (endpoint << 15);
  1140. }
  1141.  
  1142. /* Create various pipes... */
  1143. #define usb_sndctrlpipe(dev,endpoint)    \
  1144.     ((PIPE_CONTROL << 30) | __create_pipe(dev,endpoint))
  1145. #define usb_rcvctrlpipe(dev,endpoint)    \
  1146.     ((PIPE_CONTROL << 30) | __create_pipe(dev,endpoint) | USB_DIR_IN)
  1147. #define usb_sndisocpipe(dev,endpoint)    \
  1148.     ((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev,endpoint))
  1149. #define usb_rcvisocpipe(dev,endpoint)    \
  1150.     ((PIPE_ISOCHRONOUS << 30) | __create_pipe(dev,endpoint) | USB_DIR_IN)
  1151. #define usb_sndbulkpipe(dev,endpoint)    \
  1152.     ((PIPE_BULK << 30) | __create_pipe(dev,endpoint))
  1153. #define usb_rcvbulkpipe(dev,endpoint)    \
  1154.     ((PIPE_BULK << 30) | __create_pipe(dev,endpoint) | USB_DIR_IN)
  1155. #define usb_sndintpipe(dev,endpoint)    \
  1156.     ((PIPE_INTERRUPT << 30) | __create_pipe(dev,endpoint))
  1157. #define usb_rcvintpipe(dev,endpoint)    \
  1158.     ((PIPE_INTERRUPT << 30) | __create_pipe(dev,endpoint) | USB_DIR_IN)
  1159.  
  1160. /*-------------------------------------------------------------------------*/
  1161.  
  1162. static inline __u16
  1163. usb_maxpacket(struct usb_device *udev, int pipe, int is_out)
  1164. {
  1165.     struct usb_host_endpoint    *ep;
  1166.     unsigned            epnum = usb_pipeendpoint(pipe);
  1167.  
  1168.     if (is_out) {
  1169.         WARN_ON(usb_pipein(pipe));
  1170.         ep = udev->ep_out[epnum];
  1171.     } else {
  1172.         WARN_ON(usb_pipeout(pipe));
  1173.         ep = udev->ep_in[epnum];
  1174.     }
  1175.     if (!ep)
  1176.         return 0;
  1177.  
  1178.     /* NOTE:  only 0x07ff bits are for packet size... */
  1179.     return le16_to_cpu(ep->desc.wMaxPacketSize);
  1180. }
  1181.  
  1182. /* ----------------------------------------------------------------------- */
  1183.  
  1184. /* Events from the usb core */
  1185. #define USB_DEVICE_ADD        0x0001
  1186. #define USB_DEVICE_REMOVE    0x0002
  1187. #define USB_BUS_ADD        0x0003
  1188. #define USB_BUS_REMOVE        0x0004
  1189. extern void usb_register_notify(struct notifier_block *nb);
  1190. extern void usb_unregister_notify(struct notifier_block *nb);
  1191.  
  1192. #ifdef DEBUG
  1193. #define dbg(format, arg...) printk(KERN_DEBUG "%s: " format "\n" , \
  1194.     __FILE__ , ## arg)
  1195. #else
  1196. #define dbg(format, arg...) do {} while (0)
  1197. #endif
  1198.  
  1199. #define err(format, arg...) printk(KERN_ERR "%s: " format "\n" , \
  1200.     __FILE__ , ## arg)
  1201. #define info(format, arg...) printk(KERN_INFO "%s: " format "\n" , \
  1202.     __FILE__ , ## arg)
  1203. #define warn(format, arg...) printk(KERN_WARNING "%s: " format "\n" , \
  1204.     __FILE__ , ## arg)
  1205.  
  1206.  
  1207. #endif  /* __KERNEL__ */
  1208.  
  1209. #endif
  1210.