USB stack architecture

Could someone give a two-minute rundown on how the USB stack is organised?

Am I right in thinking the hierarchy goes something like:

{OHCIDriver, EHCIDriver} → {USBDriver} → {DeviceFS} → {SCSISoftUSB, hub/mouse/keyboard/printer drivers)

Where do all the hub/HID/printer drivers live? In USBDriver, based on the NetBSD code? How is USBDriver organised?

Is all the code in mixed/RiscOS/Sources/HWSupport/USB/ (apart from SCSISoftUSB) or does some live elsewhere?

Is the directory mixed/RiscOS/Sources/HWSupport/USB/Prototypes/ for testing the OHCIDriver? Or is it for testing devices without having run the full stack (OHCIDriver/USBDriver) and just skips the bits where they would be?

And a question for Jeffrey… how did you go about getting the Beagle USB up? Presumably you started by writing MUSBDriver, but how did you test it? Did you use some simple test cases (perhaps some of the examples mentioned above)? Or did you just load the rest of the stack and tweaked the driver until something worked?

Thanks!

And a followup question… how does the Castle USB podule software relate to the Iyonix USB implementation? The podule has modules USBop (low level stuff?), USBReport, USBMice and USBKeybd, which don’t seem to fit in with the stack above. There’s a PHCIDriver in ROOL CVS which seems to be targeted at the podule but, looking at Castle’s USB podule firmware, neither it nor USBDriver are anywhere to be seen. And the podule firmware seems to post-date PHCIDriver.

Was the podule an implementation of the DeviceFS USB API but written outside Pace, while PHCIDriver was Pace’s implementation on the same hardware? Or is PHCIDriver a red herring, for different podule hardware from the Castle card? It seems to be hardcoded to use slot 0, which looks a bit fishy to me.

Are Castle’s USB modules (USBop, USBKeybd etc) covered by the ROOL licence?

Am I right in thinking the hierarchy goes something like:

{OHCIDriver, EHCIDriver} → {USBDriver} → {DeviceFS} → {SCSISoftUSB, hub/mouse/keyboard/printer drivers)

Correct (ish – see below)

Where do all the hub/HID/printer drivers live? In USBDriver, based on the NetBSD code?

The hub & HID code lives in USBDriver, and is a port of the NetBSD code. And since it’s kept internal to USBDriver, it’s able to bypass the DeviceFS interface and talk to the lower-level drivers directly.

I believe all the USB printer code is here in the source tree.

How is USBDriver organised?

There are basically three parts:

• The NetBSD core, containing the core hub & protocol implementation, and the HID drivers.
• The backend for talking to the USB controller drivers. Service calls are used to register & deregister USB controllers (I think!), and a set of assembler veneers are used to pass control between the USBDriver and the hardware driver, and vice-versa.
• The RISC OS frontend – the module frontend, glue code to allow the NetBSD code to run on RISC OS, and the DeviceFS interface so regular programs can communicate with devices.

With regards to how it’s laid out in the source tree, the NetBSD/build folder contains all the RISC OS-specific bits, and the NetBSD/dev folder contains all the NetBSD bits (with some RISC OS modifications made, usually inside #ifdef riscos). This means that to build EHCIDriver, the core EHCI driver code from NetBSD/dev is needed, as well as the RISC OS frontend from NetBSD/build. Makefile hackery is used to allow the one makefile to build either one of the three different modules (USBDriver, EHCIDriver, OHCIDriver) – although it isn’t a perfect process at the moment since the modules always get partially rebuilt, so even for a minor code change I have to sit and twiddle my thumbs for an extra minute or two waiting for the ROM image to build :(

And a question for Jeffrey… how did you go about getting the Beagle USB up? Presumably you started by writing MUSBDriver, but how did you test it?

Actually since I have a rev C board I started by patching the EHCIDriver so it can use the HAL USB API to detect USB controllers, like the “rhenium” version of OHCIDriver. Then once I’d had enough fun taunting rev B owners I started on the MUSBDriver ;)

The process was basically:

1. Copy EHCIDriver source code and rip out all the bits that talk to the hardware, so that all that’s left is the software root hub implementation (the software root hub is the interface between the operating system’s USB stack of choice and the USB hardware). This meant an MUSB hub device would appear in the output of *usbdevices, but it wouldn’t do anything interesting.
2. Write the peripheral-mode driver. This driver doesn’t do any communication with RISC OS or the NetBSD stack, but it was a good place to start, especially since I hadn’t yet worked out how to get the controller into host mode.
3. Start writing the host-mode driver. There are four types of data transfer defined by the USB spec – Control, Bulk, Interrupt and Isochronous. Control is the one used for performing basic device setup (reading its device ID, programming its bus address, etc.), so I started with that. A bit of extra code was also needed in the software root hub in order to notify RISC OS when you connect a device to the port (Then on receipt of that notification, the USBDriver will attempt to query & configure the device using the Control transfers). So once Control transfers were working I was able to connect a device and see it in the *usbdevices list.
4. Once Control transfers were working I moved onto Interrupt transfers – these are used for hubs (for notifying the host of devices being connected/removed) and for HID devices. As you’d expect, this then allowed hubs, keyboards & mice to work.
5. Bulk transfers were next, since they’re used for mass-storage devices, and most other devices. This was fairly quick to get working since for the MUSB controller there are very few differences between setting up bulk & interrupt transfers.
6. Isochronous transfers still aren’t implemented. But in my defence, the EHCIDriver doesn’t have support for them either ;) I don’t think many devices use isochronous transfers – and there probably aren’t any at all for which RISC OS drivers exist – so it’s probably more sensible for me to work on fixing all the current bugs in the MUSBDriver before I go adding new features no-one will ever use!

Or did you just load the rest of the stack and tweaked the driver until something worked?

Because of the dependencies between the driver modules, this is really the only way to test a new USB controller driver. With debugging enabled you can get lots of debug output, which helps a lot when trying to work out what USBDriver is trying to do and what results it’s expecting to receive. And of course reading the appropriate bits of the USB spec was a big help!

Thanks. Never having seen them, do the XAT HID drivers disable the HID stuff in USBDriver, or do they work together?

Interesting that you didn’t use the test harnesses to at least get something up… past experience suggests you don’t want to try something with the whole stack until you know at least the basics are up (eg look for successful ethernet packets being received before you plumb into the IP stack and try TCP). I suppose once you’ve reached that point you do need the full stack to debug the corner cases.