Merge branch 'for-linus' of git://git390.osdl.marist.edu/pub/scm/linux-2.6

[pandora-kernel.git] / include / linux / usb / ch9.h

diff --git a/include/linux/usb/ch9.h b/include/linux/usb/ch9.h
index 245c725..7e0d308 100644 (file)
--- a/include/linux/usb/ch9.h
+++ b/include/linux/usb/ch9.h
@@ -1,8 +1,9 @@
 /*
- * This file holds USB constants and structures that are needed for USB
- * device APIs.  These are used by the USB device model, which is defined
- * in chapter 9 of the USB 2.0 specification.  Linux has several APIs in C
- * that need these:
+ * This file holds USB constants and structures that are needed for
+ * USB device APIs.  These are used by the USB device model, which is
+ * defined in chapter 9 of the USB 2.0 specification and in the
+ * Wireless USB 1.0 (spread around).  Linux has several APIs in C that
+ * need these:
  *
  * - the master/host side Linux-USB kernel driver API;
  * - the "usbfs" user space API; and
@@ -14,6 +15,19 @@
  *
  * There's also "Wireless USB", using low power short range radios for
  * peripheral interconnection but otherwise building on the USB framework.
+ *
+ * Note all descriptors are declared '__attribute__((packed))' so that:
+ *
+ * [a] they never get padded, either internally (USB spec writers
+ *     probably handled that) or externally;
+ *
+ * [b] so that accessing bigger-than-a-bytes fields will never
+ *     generate bus errors on any platform, even when the location of
+ *     its descriptor inside a bundle isn't "naturally aligned", and
+ *
+ * [c] for consistency, removing all doubt even when it appears to
+ *     someone that the two other points are non-issues for that
+ *     particular descriptor type.
  */
 
 #ifndef __LINUX_USB_CH9_H
@@ -52,8 +66,8 @@
 #define USB_RECIP_ENDPOINT             0x02
 #define USB_RECIP_OTHER                        0x03
 /* From Wireless USB 1.0 */
-#define USB_RECIP_PORT                         0x04
-#define USB_RECIP_RPIPE                0x05
+#define USB_RECIP_PORT                 0x04
+#define USB_RECIP_RPIPE                0x05
 
 /*
  * Standard requests, for the bRequest field of a SETUP packet.
@@ -88,10 +102,16 @@
 #define USB_REQ_LOOPBACK_DATA_READ     0x16
 #define USB_REQ_SET_INTERFACE_DS       0x17
 
+/* The Link Power Mangement (LPM) ECN defines USB_REQ_TEST_AND_SET command,
+ * used by hubs to put ports into a new L1 suspend state, except that it
+ * forgot to define its number ...
+ */
+
 /*
  * USB feature flags are written using USB_REQ_{CLEAR,SET}_FEATURE, and
  * are read as a bit array returned by USB_REQ_GET_STATUS.  (So there
- * are at most sixteen features of each type.)
+ * are at most sixteen features of each type.)  Hubs may also support a
+ * new USB_REQ_TEST_AND_SET_FEATURE to put ports into L1 suspend.
  */
 #define USB_DEVICE_SELF_POWERED                0       /* (read only) */
 #define USB_DEVICE_REMOTE_WAKEUP       1       /* dev may initiate wakeup */
@@ -166,13 +186,17 @@ struct usb_ctrlrequest {
 #define USB_DT_WIRELESS_ENDPOINT_COMP  0x11
 #define USB_DT_WIRE_ADAPTER            0x21
 #define USB_DT_RPIPE                   0x22
+#define USB_DT_CS_RADIO_CONTROL                0x23
 
-/* conventional codes for class-specific descriptors */
-#define USB_DT_CS_DEVICE               0x21
-#define USB_DT_CS_CONFIG               0x22
-#define USB_DT_CS_STRING               0x23
-#define USB_DT_CS_INTERFACE            0x24
-#define USB_DT_CS_ENDPOINT             0x25
+/* Conventional codes for class-specific descriptors.  The convention is
+ * defined in the USB "Common Class" Spec (3.11).  Individual class specs
+ * are authoritative for their usage, not the "common class" writeup.
+ */
+#define USB_DT_CS_DEVICE               (USB_TYPE_CLASS | USB_DT_DEVICE)
+#define USB_DT_CS_CONFIG               (USB_TYPE_CLASS | USB_DT_CONFIG)
+#define USB_DT_CS_STRING               (USB_TYPE_CLASS | USB_DT_STRING)
+#define USB_DT_CS_INTERFACE            (USB_TYPE_CLASS | USB_DT_INTERFACE)
+#define USB_DT_CS_ENDPOINT             (USB_TYPE_CLASS | USB_DT_ENDPOINT)
 
 /* All standard descriptors have these 2 fields at the beginning */
 struct usb_descriptor_header {
@@ -557,7 +581,9 @@ enum usb_device_state {
        /* NOTE:  there are actually four different SUSPENDED
         * states, returning to POWERED, DEFAULT, ADDRESS, or
         * CONFIGURED respectively when SOF tokens flow again.
+        * At this level there's no difference between L1 and L2
+        * suspend states.  (L2 being original USB 1.1 suspend.)
         */
 };
 
-#endif /* __LINUX_USB_CH9_H */
+#endif /* __LINUX_USB_CH9_H */