[PATCH] USB: UHCI: Spruce up some comments

This patch (as570) changes some comments in the uhci-hcd header file and
removes an unused declaration (something I forgot to erase in an earlier
patch).

Signed-off-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

 drivers/usb/host/uhci-hcd.h |   91 +++++++++++++++++++++++---------------------
 1 file changed, 49 insertions(+), 42 deletions(-)

1 files changed, 49 insertions, 42 deletions

diff --git a/drivers/usb/host/uhci-hcd.h b/drivers/usb/host/uhci-hcd.h
index b04d99df0a0e..e576db57a926 100644
--- a/drivers/usb/host/uhci-hcd.h
+++ b/drivers/usb/host/uhci-hcd.h
@@ -7,6 +7,7 @@
 #define usb_packetid(pipe)      (usb_pipein(pipe) ? USB_PID_IN : USB_PID_OUT)
 #define PIPE_DEVEP_MASK         0x0007ff00
 
+
 /*
  * Universal Host Controller Interface data structures and defines
  */
@@ -82,15 +83,10 @@
 #define UHCI_MAX_SOF_NUMBER     2047    /* in an SOF packet */
 #define CAN_SCHEDULE_FRAMES     1000    /* how far future frames can be scheduled */
 
-struct uhci_frame_list {
-        __le32 frame[UHCI_NUMFRAMES];
-
-        void *frame_cpu[UHCI_NUMFRAMES];
 
-        dma_addr_t dma_handle;
-};
-
-struct urb_priv;
+/*
+ *      Queue Headers
+ */
 
 /*
  * One role of a QH is to hold a queue of TDs for some endpoint.  Each QH is
@@ -116,13 +112,13 @@ struct uhci_qh {
 
         struct urb_priv *urbp;
 
-        struct list_head list;          /* P: uhci->frame_list_lock */
-        struct list_head remove_list;   /* P: uhci->remove_list_lock */
+        struct list_head list;
+        struct list_head remove_list;
 } __attribute__((aligned(16)));
 
 /*
  * We need a special accessor for the element pointer because it is
- * subject to asynchronous updates by the controller
+ * subject to asynchronous updates by the controller.
  */
 static __le32 inline qh_element(struct uhci_qh *qh) {
         __le32 element = qh->element;
@@ -131,6 +127,11 @@ static __le32 inline qh_element(struct uhci_qh *qh) {
         return element;
 }
 
+
+/*
+ *      Transfer Descriptors
+ */
+
 /*
  * for TD <status>:
  */
@@ -183,17 +184,10 @@ static __le32 inline qh_element(struct uhci_qh *qh) {
  *
  * That's silly, the hardware doesn't care. The hardware only cares that
  * the hardware words are 16-byte aligned, and we can have any amount of
- * sw space after the TD entry as far as I can tell.
- *
- * But let's just go with the documentation, at least for 32-bit machines.
- * On 64-bit machines we probably want to take advantage of the fact that
- * hw doesn't really care about the size of the sw-only area.
- *
- * Alas, not anymore, we have more than 4 words for software, woops.
- * Everything still works tho, surprise! -jerdfelt
+ * sw space after the TD entry.
  *
  * td->link points to either another TD (not necessarily for the same urb or
- * even the same endpoint), or nothing (PTR_TERM), or a QH (for queued urbs)
+ * even the same endpoint), or nothing (PTR_TERM), or a QH (for queued urbs).
  */
 struct uhci_td {
         /* Hardware fields */
@@ -205,16 +199,16 @@ struct uhci_td {
         /* Software fields */
         dma_addr_t dma_handle;
 
-        struct list_head list;          /* P: urb->lock */
-        struct list_head remove_list;   /* P: uhci->td_remove_list_lock */
+        struct list_head list;
+        struct list_head remove_list;
 
         int frame;                      /* for iso: what frame? */
-        struct list_head fl_list;       /* P: uhci->frame_list_lock */
+        struct list_head fl_list;
 } __attribute__((aligned(16)));
 
 /*
  * We need a special accessor for the control/status word because it is
- * subject to asynchronous updates by the controller
+ * subject to asynchronous updates by the controller.
  */
 static u32 inline td_status(struct uhci_td *td) {
         __le32 status = td->status;
@@ -225,6 +219,10 @@ static u32 inline td_status(struct uhci_td *td) {
 
 
 /*
+ *      Skeleton Queue Headers
+ */
+
+/*
  * The UHCI driver places Interrupt, Control and Bulk into QH's both
  * to group together TD's for one transfer, and also to faciliate queuing
  * of URB's. To make it easy to insert entries into the schedule, we have
@@ -254,15 +252,15 @@ static u32 inline td_status(struct uhci_td *td) {
  *
  * The terminating QH is used for 2 reasons:
  * - To place a terminating TD which is used to workaround a PIIX bug
- *   (see Intel errata for explanation)
+ *   (see Intel errata for explanation), and
  * - To loop back to the full-speed control queue for full-speed bandwidth
- *   reclamation
+ *   reclamation.
  *
  * Isochronous transfers are stored before the start of the skeleton
  * schedule and don't use QH's. While the UHCI spec doesn't forbid the
- * use of QH's for Isochronous, it doesn't use them either. Since we don't
- * need to use them either, we follow the spec diagrams in hope that it'll
- * be more compatible with future UHCI implementations.
+ * use of QH's for Isochronous, it doesn't use them either. And the spec
+ * says that queues never advance on an error completion status, which
+ * makes them totally unsuitable for Isochronous transfers.
  */
 
 #define UHCI_NUM_SKELQH         12
@@ -312,8 +310,13 @@ static inline int __interval_to_skel(int interval)
         return 0;                               /* int128 for 128-255 ms (Max.) */
 }
 
+
+/*
+ *      The UHCI controller and root hub
+ */
+
 /*
- * States for the root hub.
+ * States for the root hub:
  *
  * To prevent "bouncing" in the presence of electrical noise,
  * when there are no devices attached we delay for 1 second in the
@@ -324,7 +327,7 @@ static inline int __interval_to_skel(int interval)
  */
 enum uhci_rh_state {
         /* In the following states the HC must be halted.
-         * These two must come first */
+         * These two must come first. */
         UHCI_RH_RESET,
         UHCI_RH_SUSPENDED,
 
@@ -336,13 +339,13 @@ enum uhci_rh_state {
         UHCI_RH_SUSPENDING,
 
         /* In the following states it's an error if the HC is halted.
-         * These two must come last */
+         * These two must come last. */
         UHCI_RH_RUNNING,                /* The normal state */
         UHCI_RH_RUNNING_NODEVS,         /* Running with no devices attached */
 };
 
 /*
- * This describes the full uhci information.
+ * The full UHCI controller information:
  */
 struct uhci_hcd {
 
@@ -361,7 +364,7 @@ struct uhci_hcd {
         spinlock_t lock;
 
         dma_addr_t frame_dma_handle;            /* Hardware frame list */
-        __le32 *frame;                          /* P: uhci->lock */
+        __le32 *frame;
         void **frame_cpu;                       /* CPU's frame list */
 
         int fsbr;                               /* Full-speed bandwidth reclamation */
@@ -387,22 +390,22 @@ struct uhci_hcd {
         unsigned long ports_timeout;            /* Time to stop signalling */
 
         /* Main list of URB's currently controlled by this HC */
-        struct list_head urb_list;              /* P: uhci->lock */
+        struct list_head urb_list;
 
         /* List of QH's that are done, but waiting to be unlinked (race) */
-        struct list_head qh_remove_list;        /* P: uhci->lock */
+        struct list_head qh_remove_list;
         unsigned int qh_remove_age;             /* Age in frames */
 
         /* List of TD's that are done, but waiting to be freed (race) */
-        struct list_head td_remove_list;        /* P: uhci->lock */
+        struct list_head td_remove_list;
         unsigned int td_remove_age;             /* Age in frames */
 
         /* List of asynchronously unlinked URB's */
-        struct list_head urb_remove_list;       /* P: uhci->lock */
+        struct list_head urb_remove_list;
         unsigned int urb_remove_age;            /* Age in frames */
 
         /* List of URB's awaiting completion callback */
-        struct list_head complete_list;         /* P: uhci->lock */
+        struct list_head complete_list;
 
         int rh_numports;                        /* Number of root-hub ports */
 
@@ -421,13 +424,17 @@ static inline struct usb_hcd *uhci_to_hcd(struct uhci_hcd *uhci)
 
 #define uhci_dev(u)     (uhci_to_hcd(u)->self.controller)
 
+
+/*
+ *      Private per-URB data
+ */
 struct urb_priv {
         struct list_head urb_list;
 
         struct urb *urb;
 
         struct uhci_qh *qh;             /* QH for this URB */
-        struct list_head td_list;       /* P: urb->lock */
+        struct list_head td_list;
 
         unsigned fsbr : 1;              /* URB turned on FSBR */
         unsigned fsbr_timeout : 1;      /* URB timed out on FSBR */
@@ -438,9 +445,10 @@ struct urb_priv {
 
         unsigned long fsbrtime;         /* In jiffies */
 
-        struct list_head queue_list;    /* P: uhci->frame_list_lock */
+        struct list_head queue_list;
 };
 
+
 /*
  * Locking in uhci.c
  *
@@ -460,6 +468,5 @@ struct urb_priv {
 
 #define PCI_VENDOR_ID_GENESYS           0x17a0
 #define PCI_DEVICE_ID_GL880S_UHCI       0x8083
-#define PCI_DEVICE_ID_GL880S_EHCI       0x8084
 
 #endif