[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(-)
This commit is contained in:
Alan Stern
Greg Kroah-Hartman
parent
d09d36a91c
commit
8b262bd255
|
|
@ -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;
|
||||
|
|
@ -224,6 +218,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
|
||||
|
|
@ -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.) */
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
* States for the root hub.
|
||||
* The UHCI controller and 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue