1===========
2EHCI driver
3===========
4
527-Dec-2002
6
7The EHCI driver is used to talk to high speed USB 2.0 devices using
8USB 2.0-capable host controller hardware.  The USB 2.0 standard is
9compatible with the USB 1.1 standard. It defines three transfer speeds:
10
11    - "High Speed" 480 Mbit/sec (60 MByte/sec)
12    - "Full Speed" 12 Mbit/sec (1.5 MByte/sec)
13    - "Low Speed" 1.5 Mbit/sec
14
15USB 1.1 only addressed full speed and low speed.  High speed devices
16can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds.
17
18USB 1.1 devices may also be used on USB 2.0 systems.  When plugged
19into an EHCI controller, they are given to a USB 1.1 "companion"
20controller, which is a OHCI or UHCI controller as normally used with
21such devices.  When USB 1.1 devices plug into USB 2.0 hubs, they
22interact with the EHCI controller through a "Transaction Translator"
23(TT) in the hub, which turns low or full speed transactions into
24high speed "split transactions" that don't waste transfer bandwidth.
25
26At this writing, this driver has been seen to work with implementations
27of EHCI from (in alphabetical order):  Intel, NEC, Philips, and VIA.
28Other EHCI implementations are becoming available from other vendors;
29you should expect this driver to work with them too.
30
31While usb-storage devices have been available since mid-2001 (working
32quite speedily on the 2.4 version of this driver), hubs have only
33been available since late 2001, and other kinds of high speed devices
34appear to be on hold until more systems come with USB 2.0 built-in.
35Such new systems have been available since early 2002, and became much
36more typical in the second half of 2002.
37
38Note that USB 2.0 support involves more than just EHCI.  It requires
39other changes to the Linux-USB core APIs, including the hub driver,
40but those changes haven't needed to really change the basic "usbcore"
41APIs exposed to USB device drivers.
42
43- David Brownell
44  <dbrownell@users.sourceforge.net>
45
46
47Functionality
48=============
49
50This driver is regularly tested on x86 hardware, and has also been
51used on PPC hardware so big/little endianness issues should be gone.
52It's believed to do all the right PCI magic so that I/O works even on
53systems with interesting DMA mapping issues.
54
55Transfer Types
56--------------
57
58At this writing the driver should comfortably handle all control, bulk,
59and interrupt transfers, including requests to USB 1.1 devices through
60transaction translators (TTs) in USB 2.0 hubs.  But you may find bugs.
61
62High Speed Isochronous (ISO) transfer support is also functional, but
63at this writing no Linux drivers have been using that support.
64
65Full Speed Isochronous transfer support, through transaction translators,
66is not yet available.  Note that split transaction support for ISO
67transfers can't share much code with the code for high speed ISO transfers,
68since EHCI represents these with a different data structure.  So for now,
69most USB audio and video devices can't be connected to high speed buses.
70
71Driver Behavior
72---------------
73
74Transfers of all types can be queued.  This means that control transfers
75from a driver on one interface (or through usbfs) won't interfere with
76ones from another driver, and that interrupt transfers can use periods
77of one frame without risking data loss due to interrupt processing costs.
78
79The EHCI root hub code hands off USB 1.1 devices to its companion
80controller.  This driver doesn't need to know anything about those
81drivers; a OHCI or UHCI driver that works already doesn't need to change
82just because the EHCI driver is also present.
83
84There are some issues with power management; suspend/resume doesn't
85behave quite right at the moment.
86
87Also, some shortcuts have been taken with the scheduling periodic
88transactions (interrupt and isochronous transfers).  These place some
89limits on the number of periodic transactions that can be scheduled,
90and prevent use of polling intervals of less than one frame.
91
92
93Use by
94======
95
96Assuming you have an EHCI controller (on a PCI card or motherboard)
97and have compiled this driver as a module, load this like::
98
99    # modprobe ehci-hcd
100
101and remove it by::
102
103    # rmmod ehci-hcd
104
105You should also have a driver for a "companion controller", such as
106"ohci-hcd"  or "uhci-hcd".  In case of any trouble with the EHCI driver,
107remove its module and then the driver for that companion controller will
108take over (at lower speed) all the devices that were previously handled
109by the EHCI driver.
110
111Module parameters (pass to "modprobe") include:
112
113    log2_irq_thresh (default 0):
114	Log2 of default interrupt delay, in microframes.  The default
115	value is 0, indicating 1 microframe (125 usec).  Maximum value
116	is 6, indicating 2^6 = 64 microframes.  This controls how often
117	the EHCI controller can issue interrupts.
118
119If you're using this driver on a 2.5 kernel, and you've enabled USB
120debugging support, you'll see three files in the "sysfs" directory for
121any EHCI controller:
122
123	"async"
124		dumps the asynchronous schedule, used for control
125		and bulk transfers.  Shows each active qh and the qtds
126		pending, usually one qtd per urb.  (Look at it with
127		usb-storage doing disk I/O; watch the request queues!)
128	"periodic"
129		dumps the periodic schedule, used for interrupt
130		and isochronous transfers.  Doesn't show qtds.
131	"registers"
132		show controller register state, and
133
134The contents of those files can help identify driver problems.
135
136
137Device drivers shouldn't care whether they're running over EHCI or not,
138but they may want to check for "usb_device->speed == USB_SPEED_HIGH".
139High speed devices can do things that full speed (or low speed) ones
140can't, such as "high bandwidth" periodic (interrupt or ISO) transfers.
141Also, some values in device descriptors (such as polling intervals for
142periodic transfers) use different encodings when operating at high speed.
143
144However, do make a point of testing device drivers through USB 2.0 hubs.
145Those hubs report some failures, such as disconnections, differently when
146transaction translators are in use; some drivers have been seen to behave
147badly when they see different faults than OHCI or UHCI report.
148
149
150Performance
151===========
152
153USB 2.0 throughput is gated by two main factors:  how fast the host
154controller can process requests, and how fast devices can respond to
155them.  The 480 Mbit/sec "raw transfer rate" is obeyed by all devices,
156but aggregate throughput is also affected by issues like delays between
157individual high speed packets, driver intelligence, and of course the
158overall system load.  Latency is also a performance concern.
159
160Bulk transfers are most often used where throughput is an issue.  It's
161good to keep in mind that bulk transfers are always in 512 byte packets,
162and at most 13 of those fit into one USB 2.0 microframe.  Eight USB 2.0
163microframes fit in a USB 1.1 frame; a microframe is 1 msec/8 = 125 usec.
164
165So more than 50 MByte/sec is available for bulk transfers, when both
166hardware and device driver software allow it.  Periodic transfer modes
167(isochronous and interrupt) allow the larger packet sizes which let you
168approach the quoted 480 MBit/sec transfer rate.
169
170Hardware Performance
171--------------------
172
173At this writing, individual USB 2.0 devices tend to max out at around
17420 MByte/sec transfer rates.  This is of course subject to change;
175and some devices now go faster, while others go slower.
176
177The first NEC implementation of EHCI seems to have a hardware bottleneck
178at around 28 MByte/sec aggregate transfer rate.  While this is clearly
179enough for a single device at 20 MByte/sec, putting three such devices
180onto one bus does not get you 60 MByte/sec.  The issue appears to be
181that the controller hardware won't do concurrent USB and PCI access,
182so that it's only trying six (or maybe seven) USB transactions each
183microframe rather than thirteen.  (Seems like a reasonable trade off
184for a product that beat all the others to market by over a year!)
185
186It's expected that newer implementations will better this, throwing
187more silicon real estate at the problem so that new motherboard chip
188sets will get closer to that 60 MByte/sec target.  That includes an
189updated implementation from NEC, as well as other vendors' silicon.
190
191There's a minimum latency of one microframe (125 usec) for the host
192to receive interrupts from the EHCI controller indicating completion
193of requests.  That latency is tunable; there's a module option.  By
194default ehci-hcd driver uses the minimum latency, which means that if
195you issue a control or bulk request you can often expect to learn that
196it completed in less than 250 usec (depending on transfer size).
197
198Software Performance
199--------------------
200
201To get even 20 MByte/sec transfer rates, Linux-USB device drivers will
202need to keep the EHCI queue full.  That means issuing large requests,
203or using bulk queuing if a series of small requests needs to be issued.
204When drivers don't do that, their performance results will show it.
205
206In typical situations, a usb_bulk_msg() loop writing out 4 KB chunks is
207going to waste more than half the USB 2.0 bandwidth.  Delays between the
208I/O completion and the driver issuing the next request will take longer
209than the I/O.  If that same loop used 16 KB chunks, it'd be better; a
210sequence of 128 KB chunks would waste a lot less.
211
212But rather than depending on such large I/O buffers to make synchronous
213I/O be efficient, it's better to just queue up several (bulk) requests
214to the HC, and wait for them all to complete (or be canceled on error).
215Such URB queuing should work with all the USB 1.1 HC drivers too.
216
217In the Linux 2.5 kernels, new usb_sg_*() api calls have been defined; they
218queue all the buffers from a scatterlist.  They also use scatterlist DMA
219mapping (which might apply an IOMMU) and IRQ reduction, all of which will
220help make high speed transfers run as fast as they can.
221
222
223TBD:
224   Interrupt and ISO transfer performance issues.  Those periodic
225   transfers are fully scheduled, so the main issue is likely to be how
226   to trigger "high bandwidth" modes.
227
228TBD:
229   More than standard 80% periodic bandwidth allocation is possible
230   through sysfs uframe_periodic_max parameter. Describe that.
231