USB: add rationale on why usb descriptor structures have to be packed
authorInaky Perez-Gonzalez <inaky@linux.intel.com>
Fri, 23 Feb 2007 00:37:53 +0000 (16:37 -0800)
committerGreg Kroah-Hartman <gregkh@suse.de>
Fri, 23 Feb 2007 23:03:46 +0000 (15:03 -0800)
Add argumentation in defense of using __attribute__((packed)) in USB
descriptors authored by Dave Brownell. Necessary as in some cases it
seems superfluous.

Signed-off-by: Inaky Perez-Gonzalez <inaky@linux.intel.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
include/linux/usb/ch9.h

index 245c72531228346982598506248d68fa03d16461..1122a6c2c1a3dc3759c1dee7ef6988f24240dee3 100644 (file)
@@ -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
  *
  * 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