MUSBDriver

MUSBDriver

Introduction

The MUSBDriver module, located at RiscOS/Sources/HWSupport/USB/Controllers/MUSBDriver in gitlab, is a driver for the Mentor MUSBMHDRC USB OTG controller. It integrates with the core USBDriver module to allow RISC OS to interact with attached devices when the controller is operating in host-mode. The MUSBDriver also provides a simple peripheral-mode driver, so that boards which use the MSUBMHDRC will appear as an attached device when connected to another computer. The driver is far from complete, and many improvements are possible, most of which are listed on this page.

Current functionality & limitations

Host mode

• Control, bulk & interrupt endpoints are supported.
• Isochronous endpoints are currently not supported. (I don’t have any hardware to test with – JL)
• The driver currently uses a fixed endpoint allocation scheme. There can be an unlimited number of control pipes open, but there’s a limit of 15 transmit bulk/interrupt pipes and 15 receive bulk/interrupt pipes. Most devices require only one or two pipes in each direction, so it’s expected that anywhere between 8 and 15 devices can be connected before the driver will begin to fail.
• DMA is not supported. Once bottlenecks elsewhere in RISC OS have been resolved (e.g. the USB mass storage drivers) it should be possible to implement DMA support and tweak the driver for best performance.
• Aborted pipes aren’t handled cleanly. Aborted pipes should now be handled cleanly, although the code could do with reviewing once dynamic endpoint allocation is implemented.
• The driver doesn’t yet implement all the required aspects of the root hub driver (e.g. port power control), or deal with all hardware interrupts in the correct manner (e.g. cancelling any active pipes when VBUS errors or disconnect interrupts occur)

Peripheral mode

• At present the machine will appear as a dummy “RISC OS computer” device when conected to another machine.
• There are likely some aspects of the peripheral implementation which don’t abide by the USB spec.

OTG/other features

• HNP and SRP are not yet supported
• At present there is very little code to handle the transition from host to peripheral mode, and vice-versa. This means the driver state may not be set or reset correctly, and unexpected side-effects may occur (e.g. attempting to initiate a host-mode transaction when in peripheral mode).

Debugging

The MUSBDriver can be debugged in a similar way to the other USB modules. For building an OMAP3 ROM with debug USB drivers:

1. Open the components file (BuildSys.Components.OMAP3) and scroll down to the USB modules. Comment out the “USB drivers – non-debug” lines, and un-comment out the “USB drivers – debug” lines.
2. DADebug is the recommended way of getting debug output from the drivers. Make sure that the module is part of the ROM build, and that it becomes before the USB drivers in the link order
3. Make sure that your chosen debug output device (i.e. DADebug) is actually selected in the driver source code! You’ll find the relevant code in module_init() inside cmodule.c (from MUSBDriver) and ehcimodule.c & usbmodule.c (from HWSupport.USB.NetBSD.build)
4. If necessary, enable the debug terminal in Kernel.hdr.Options, so that you have a fairly reliable way of getting debug logs out of the machine.
5. Build the ROM image as normal (“Make ROM”, “Install ROM” and “Join ROM” should be the only steps needed if you’ve already got a working build tree)
6. When running the ROM, the USB modules (USBDriver, EHCIDriver, MUSBDriver) will now have extra commands available to view their internal states and control the level of debug logging.
   1. For the MUSBDriver, any debug level above 10 will generally show what’s going on in the interrupt handlers, and any debug level above 20 will show the contents of the individual packets as they are loaded into and out of the FIFOs.
   2. ‘*MUSBState’ will show the overall state of the driver software (including the status of each endpoint), while ‘*MUSBRegs’ will show the state of the majority of the hardware registers.
7. If DADebug is in use, you can use *DADPrint and *DADReset to interact with the contents of the debug log buffer.

Other notes/TODO list

• The core USB module isn’t aware that the OTG controller often isn’t able to supply the 500mA current that’s the norm for powered hubs. Some improvement (perhaps just claiming that the hub is bus-powered) may be needed to prevent unexpected failures due to use of bus-powered peripherals.
• There’s some room to tidy up the interrupt handler routines and optimise them for speed.
• There’s currently no support for dynamic FIFO resizing, and the current FIFOs are fixes at 512 bytes. It’s unknown if this will cause any problems with devices which have a maximum packet size over 512 bytes.
• When DMA support is added, it would be advantageous if it was possible for musb_allocm to make a decision as to whether a particular transfer should go via DMA or not (and thus whether cacheable or non-cacheable RAM should be allocated). The DMA controller in the MUSB supports 8 channels, thus only 8 endpoints can use DMA at any time; also DMA on endpoint 0 (the only endpoint which can perform control transfers) is not possible, so single-mindedly forcing all transfers to use uncacheable memory will just hurt performance.
• There’s currently no support for packet double-buffering. Adding support may provide a significant boost to performance, especially when DMA is not being used.
• Packet auto-request is also not supported (I believe this feature is mainly for DMA, to further reduce the burden on the CPU interrupt handler – JL)
• etc. – see the source code for any other bits that need improving!