[PATCH] usbcore doc + minor fixes

Cleaning out my queue of most minor patches:

  - Provides some kerneldoc for 'struct usb_interface' now that
    the API is highlighting it.

  - Fixes usb_set_interface() so it doesn't affect other interfaces.

    This provides the right place for an eventual HCD call to clean
    out now-invalid records of endpoint state, and also gets rid of
    a potential SMP issue where drivers on different interfaces
    calling concurrently could clobber each other.  (Per-interface
    data doesn't need locking except against config changes.)

  - It's OK to pass URB_NO_INTERRUPT hints if you're queueing a
    bunch of interrupt transfers.

The set_interface call should eventually take the interface as a
parameter, it's one of the few left using the "device plus magic
number" identifier.  I have a partial patch for that, but it doesn't
handle the (newish) ALSA usb audio driver or a few other callers.

1 files changed, 33 insertions, 3 deletions

diff --git a/include/linux/usb.h b/include/linux/usb.h
index 89ecca734172..fe144bda56f0 100644
--- a/include/linux/usb.h
+++ b/include/linux/usb.h
@@ -222,12 +222,42 @@ struct usb_interface_descriptor {
 	int extralen;
 };
 
+/**
+ * struct usb_interface - what usb device drivers talk to
+ * @altsetting: array of interface descriptors, one for each alternate
+ * 	setting that may be selected.  each one includes a set of
+ * 	endpoint configurations.
+ * @num_altsetting: number of altsettings defined.
+ * @act_altsetting: index of current altsetting.  this number is always
+ *	less than num_altsetting.  after the device is configured, each
+ *	interface uses its default setting of zero.
+ * @dev: driver model's view of this device
+ *
+ * USB device drivers attach to interfaces on a physical device.  Each
+ * interface encapsulates a single high level function, such as feeding
+ * an audio stream to a speaker or reporting a change in a volume control.
+ * Many USB devices only have one interface.  The protocol used to talk to
+ * an interface's endpoints can be defined in a usb "class" specification,
+ * or by a product's vendor.  The (default) control endpoint is part of
+ * every interface, but is never listed among the interface's descriptors.
+ *
+ * The driver that is bound to the interface can use standard driver model
+ * calls such as dev_get_drvdata() on the dev member of this structure.
+ *
+ * Each interface may have alternate settings.  The initial configuration
+ * of a device sets the first of these, but the device driver can change
+ * that setting using usb_set_interface().  Alternate settings are often
+ * used to control the the use of periodic endpoints, such as by having
+ * different endpoints use different amounts of reserved USB bandwidth.
+ * All standards-conformant USB devices that use isochronous endpoints
+ * will use them in non-default settings.
+ */
 struct usb_interface {
 	struct usb_interface_descriptor *altsetting;
 
-	int act_altsetting;		/* active alternate setting */
-	int num_altsetting;		/* number of alternate settings */
-	int max_altsetting;		/* total memory allocated */
+	unsigned act_altsetting;	/* active alternate setting */
+	unsigned num_altsetting;	/* number of alternate settings */
+	unsigned max_altsetting;	/* total memory allocated */
 
 	struct usb_driver *driver;	/* driver */
 	struct device dev;		/* interface specific device info */