Ok, so on with the USB coding. I'm starting with the UHCI controller (which is one of the USB 1 standards) as my test machine has a UHCI adapter in it.
Introduction to USB
When you want the USB adapter to perform a data transfer of some sort, you create a structure called a Transfer Descriptor in memory and add it onto the end of a linked list of work. The USB adapter periodically scans this list and performs any outstanding work it finds.
As well as Transfer Descriptors, USB also has a structure called a Queue Head. These aren't important as far as what data gets sent to the devices, but they are really useful on the software side to organise and arrange Transfer Descriptors in a sensible manner. For example, we could have one Queue Head for each device to keep things tidy.
The starting point for all of this (and the first thing we need to configure) is a register in I/O space which holds the beginning of the Frame List. This is an array of 1024 pointers, each of which is the start of a separate list of work. Each millisecond, the USB adapter moves to the next entry in the frame list and does all the work.
"Why 1024 separate lists? Why not just one list?" I hear you cry. Sometimes you need to transfer data that is time dependant, such as data from a USB camera or data to a USB sound device. As one entry of the frame list is examined per millisecond, you can add work to the list that won't be processed until later on. Using the sound device example, you need to keep the sound device loaded with data at the right time so that it can keep playing, and the USB frame list allows you to queue up the next second's-worth of sound data and forget about it. USB refers to these transfers as Isochronous (in USB 1) or Periodic (in USB 2).
"But what about transfers that I want as soon as possible?" For this we create a Queue Head, and we add all this non-time dependent work to this Queue Head. This makes a list which the USB specification refers to as the Reclamation list. Each of the frame list pointers then points to the time-dependent-work-for-this-millisecond which then points to the reclamation list. Frame list pointers with no time-dependent work just point straight to the reclamation list. This means that for each millisecond, the USB adapter transfers the data that is scheduled for that millisecond, then uses the remaining time to do anything from the reclamation list that it can fit in.
Implementing
So, first off we create a Queue Head structure, and set its pointer to a special value called the TERMINATE value. This just indicates to the USB adapter that this is the end of the list and there is no more work to do. Then we allocate the Frame List which is 1024 x 32-bit integers (totalling 4KB) and set each of these entries to point to our Queue Head. Then we use the USB registers (which are in I/O space for the UHCI adapter) to tell the adapter where the frame list is, and then to set it "running".
At this point, I have verified that the USB controller is running because the Current Frame Number (another of the I/O space registers) is incrementing as the USB adapter parses the list.
Ports
The UHCI registers also contain two "Port Status and Control" registers, one for each of the physical ports connected to the adapter. These registers allow you to find out if a device is connected, how fast the device is, and allow you to reset the device so that it can be configured.
Unfortunately, these don't seem to be doing anything, I can't enable the root ports or see connected devices.
I had thought from the USB specification that the EHCI (USB 2) controller wouldn't be a problem. In a system that has both USB1 and USB2 controllers (which is most of them these days), the EHCI adapter is responsible for controlling which ports are routed to which controllers. If the EHCI controller's CONFIGURE flag is not set, the hardware routes all the ports to the companion controller (the UHCI controller that I'm using). What I suspect is happening is that the EHCI controller has been configured by the BIOS because I'm using the BIOS' Legacy Support in order to boot from the USB key in the first place, and this is messing things up.
Finding the EHCI controller
I ran the PCI scan again and there is no sign of an EHCI controller, but I pretty sure that the Revo specification says it has USB 2. I was also able to find a forum post on the web where someone had posted a device list for their Revo R3700 as they were asking for help with an unrelated issue, but it lists the EHCI controller as a function of one of the PCI devices.
After much confusion, I found a bug in the PCI scanning code that I had been using for years. Some PCI devices have multiple "functions" and these functions are addressed separately when interacting with the device. Other devices have only one function, but that function responds to all the function addresses for the device (I found this with a RealTek network card before). In order to find out if a device has many identical functions, or has one function responding to all the addresses, you read part of the PCI configuration space for a flag which indicates if it is a single-function device, which I was doing. Unfortunately, this bit can be set on functions beyond the first function of a multi-function device, and that was being misinterpreted by my code. It was getting to the second function of the multi-function device, finding this flag was set, thinking it was a single-function device (which was obviously wrong) and skipping onto the next device.
With that issue fixed, I have located the EHCI controller (and a Wireless LAN controller which apparently fitted to this machine, who knew?)
Disabling the EHCI controller
With the address of the EHCI controller, I quickly skimmed the EHCI specification and wrote some quick and dirty code to find and reset the CONFIGURE flag for the EHCI adapter which should return the control of all of the ports to the UHCI controller.
UPDATE: Don't do this. I didn't realise that I also had to "take ownership" of the EHCI controller from the BIOS as well. I didn't and that caused the system to hang for about ten seconds after I connected or disconnected a device, presumably as the BIOS tried to get the disabled EHCI controller to connect to a port that it didn't own and things got confused. Anyway, lesson learned.
Moving on from this, I also found that the EHCI controller had six ports, and the three UHCI controllers had two ports each (which makes sense) and I had to work my way through the different UHCI controllers to find the one that had my USB Flash Drive connected (it was the only port with something in).
Resetting the Ports
A bit more USB theory now. Every USB device is assigned an address by the system and that address is used when sending commands to the device, except that the address is assigned by using a command, so which came first? Well, when you reset a USB port (by using the Port Status and Control register on the USB controller) the device also resets and then responds to address 0, which is a special address specifically for this task. Once the device has been reset, you issue a Set Address command to the device at address 0 to give it a number that is not already in use. This is also why the USB system only supports 127 devices instead of 128, because address 0 cannot (well, "should" not) be used for normal transfers,
Many hours of hacking and confusion later, I have a rough function which resets the port, issues a Set Address to the device, and then sends the Get Descriptor request to read the Device Descriptor \o/
I will post this function onto the blog once I have cleaned it up. It is a very rough-and-ready single function that goes through the steps of resetting the UHCI adapter, configuring the frame list, resetting a port, and issuing a GET_DESCRIPTOR transfer to the device. I'll post it in an attempt to save others the headache of getting to this point. Just having a function like this, in my opinion, puts a great deal of the specification into context and allows a developer to research a particular flag or variable with the knowledge of where it fits into the process. On top of all that, having some functional code that can be tweaked can be used to test out various variables to see what effect each of them have, and to compare to another implementation to find differences when one works and the other doesn't. I've seen forum posts where a new developer has been asking questions about implementing a USB driver and the responses have been to go and look at another driver's source code (such as Linux) which (again, my opinion) is a terrible idea. They need a clean implementation, not one that requires days of sifting through to see past all the implementation-specific details such as how they allocate the memory or what structures they use to store the device metadata, not to mention tracking through function pointers to work out where they were set and to what? I'm really annoyed that it has taken me so long and at least three attempts to get to this point, and annoyed at the documentation for dramatically over-complicating this basic process, and annoyed at various on-line sources for not having code like this posted already. Hopefully I can try to remedy that, at least to a small degree. /rant
I've taken a bit handful of various USB devices and run this code against each of them to read the device descriptors, most of them work but some are reporting HALT errors and some of them are reporting CRC errors. I guess some of them may not be compatible with USB 1, or my code is just plain wrong somewhere. :)
In either case, I think I might leave UHCI there and take the knowledge I have gained and look at applying it to a more elegant EHCI driver next as it's likely that will be more use in the long term.
No comments:
Post a Comment