1Specification and Internals for the New UHCI Driver (Whitepaper...) 2 3 brought to you by 4 5 Georg Acher, acher@in.tum.de (executive slave) (base guitar) 6 Deti Fliegl, deti@fliegl.de (executive slave) (lead voice) 7 Thomas Sailer, sailer@ife.ee.ethz.ch (chief consultant) (cheer leader) 8 9 $Id: uhci.txt,v 1.1.1.1 2007-08-03 18:51:33 rnuti Exp $ 10 11This document and the new uhci sources can be found on 12 http://hotswap.in.tum.de/usb 13 141. General issues 15 161.1 Why a new UHCI driver, we already have one?!? 17 18Correct, but its internal structure got more and more mixed up by the (still 19ongoing) efforts to get isochronous transfers (ISO) to work. 20Since there is an increasing need for reliable ISO-transfers (especially 21for USB-audio needed by TS and for a DAB-USB-Receiver build by GA and DF), 22this state was a bit unsatisfying in our opinion, so we've decided (based 23on knowledge and experiences with the old UHCI driver) to start 24from scratch with a new approach, much simpler but at the same time more 25powerful. 26It is inspired by the way Win98/Win2000 handles USB requests via URBs, 27but it's definitely 100% free of MS-code and doesn't crash while 28unplugging an used ISO-device like Win98 ;-) 29Some code for HW setup and root hub management was taken from the 30original UHCI driver, but heavily modified to fit into the new code. 31The invention of the basic concept, and major coding were completed in two 32days (and nights) on the 16th and 17th of October 1999, now known as the 33great USB-October-Revolution started by GA, DF, and TS ;-) 34 35Since the concept is in no way UHCI dependent, we hope that it will also be 36transferred to the OHCI-driver, so both drivers share a common API. 37 381.2. Advantages and disadvantages 39 40+ All USB transfer types work now! 41+ Asynchronous operation 42+ Simple, but powerful interface (only two calls for start and cancel) 43+ Easy migration to the new API, simplified by a compatibility API 44+ Simple usage of ISO transfers 45+ Automatic linking of requests 46+ ISO transfers allow variable length for each frame and striping 47+ No CPU dependent and non-portable atomic memory access, no asm()-inlines 48+ Tested on x86 and Alpha 49 50- Rewriting for ISO transfers needed 51 521.3. Is there some compatibility to the old API? 53 54Yes, but only for control, bulk and interrupt transfers. We've implemented 55some wrapper calls for these transfer types. The usbcore works fine with 56these wrappers. For ISO there's no compatibility, because the old ISO-API 57and its semantics were unnecessary complicated in our opinion. 58 591.4. What's really working? 60 61As said above, CTRL and BULK already work fine even with the wrappers, 62so legacy code wouldn't notice the change. 63Regarding to Thomas, ISO transfers now run stable with USB audio. 64INT transfers (e.g. mouse driver) work fine, too. 65 661.5. Are there any bugs? 67 68No ;-) 69Hm... 70Well, of course this implementation needs extensive testing on all available 71hardware, but we believe that any fixes shouldn't harm the overall concept. 72 731.6. What should be done next? 74 75A large part of the request handling seems to be identical for UHCI and 76OHCI, so it would be a good idea to extract the common parts and have only 77the HW specific stuff in uhci.c. Furthermore, all other USB device drivers 78should need URBification, if they use isochronous or interrupt transfers. 79One thing missing in the current implementation (and the old UHCI driver) 80is fair queueing for BULK transfers. Since this would need (in principle) 81the alteration of already constructed TD chains (to switch from depth to 82breadth execution), another way has to be found. Maybe some simple 83heuristics work with the same effect. 84 85--------------------------------------------------------------------------- 86 872. Internal structure and mechanisms 88 89To get quickly familiar with the internal structures, here's a short 90description how the new UHCI driver works. However, the ultimate source of 91truth is only uhci.c! 92 932.1. Descriptor structure (QHs and TDs) 94 95During initialization, the following skeleton is allocated in init_skel: 96 97 framespecific | common chain 98 99framelist[] 100[ 0 ]-----> TD --> TD -------\ 101[ 1 ]-----> TD --> TD --------> TD ----> QH -------> QH -------> QH ---> NULL 102 ... TD --> TD -------/ 103[1023]-----> TD --> TD ------/ 104 105 ^^ ^^ ^^ ^^ ^^ ^^ 106 1024 TDs for 7 TDs for 1 TD for Start of Start of End Chain 107 ISO INT (2-128ms) 1ms-INT CTRL Chain BULK Chain 108 109For each CTRL or BULK transfer a new QH is allocated and the containing data 110transfers are appended as (vertical) TDs. After building the whole QH with its 111dangling TDs, the QH is inserted before the BULK Chain QH (for CTRL) or 112before the End Chain QH (for BULK). Since only the QH->next pointers are 113affected, no atomic memory operation is required. The three QHs in the 114common chain are never equipped with TDs! 115 116For ISO or INT, the TD for each frame is simply inserted into the appropriate 117ISO/INT-TD-chain for the desired frame. The 7 skeleton INT-TDs are scattered 118among the 1024 frames similar to the old UHCI driver. 119 120For CTRL/BULK/ISO, the last TD in the transfer has the IOC-bit set. For INT, 121every TD (there is only one...) has the IOC-bit set. 122 123Besides the data for the UHCI controller (2 or 4 32bit words), the descriptors 124are double-linked through the .vertical and .horizontal elements in the 125SW data of the descriptor (using the double-linked list structures and 126operations), but SW-linking occurs only in closed domains, i.e. for each of 127the 1024 ISO-chains and the 8 INT-chains there is a closed cycle. This 128simplifies all insertions and unlinking operations and avoids costly 129bus_to_virt()-calls. 130 1312.2. URB structure and linking to QH/TDs 132 133During assembly of the QH and TDs of the requested action, these descriptors 134are stored in urb->urb_list, so the allocated QH/TD descriptors are bound to 135this URB. 136If the assembly was successful and the descriptors were added to the HW chain, 137the corresponding URB is inserted into a global URB list for this controller. 138This list stores all pending URBs. 139 1402.3. Interrupt processing 141 142Since UHCI provides no means to directly detect completed transactions, the 143following is done in each UHCI interrupt (uhci_interrupt()): 144 145For each URB in the pending queue (process_urb()), the ACTIVE-flag of the 146associated TDs are processed (depending on the transfer type 147process_{transfer|interrupt|iso}()). If the TDs are not active anymore, 148they indicate the completion of the transaction and the status is calculated. 149Inactive QH/TDs are removed from the HW chain (since the host controller 150already removed the TDs from the QH, no atomic access is needed) and 151eventually the URB is marked as completed (OK or errors) and removed from the 152pending queue. Then the next linked URB is submitted. After (or immediately 153before) that, the completion handler is called. 154 1552.4. Unlinking URBs 156 157First, all QH/TDs stored in the URB are unlinked from the HW chain. 158To ensure that the host controller really left a vertical TD chain, we 159wait for one frame. After that, the TDs are physically destroyed. 160 1612.5. URB linking and the consequences 162 163Since URBs can be linked and the corresponding submit_urb is called in 164the UHCI-interrupt, all work associated with URB/QH/TD assembly has to be 165interrupt save. This forces kmalloc to use GFP_ATOMIC in the interrupt. 166