RISC OS 5 USB stack overview

The RISC OS 5 USB stack consists of the following software components:

• The USBDriver module, which implements the core of the stack. It also provides USB keyboard & mouse support, along with the DeviceFS interface that external programs must use to communicate with USB devices
• The EHCIDriver module, which is a driver for USB controllers which comply with the Enhanced Host Controller Interface specification. EHCI controllers support USB 2.
• The OHCIDriver module, which is a driver for USB controllers which comply with the Open Host Controller Interface specification. OHCI controllers only support USB 1.
• The MUSBDriver module, which is a driver for the Mentor MUSBMHDRC USB OTG controller. The MUSBMHDRC supports USB2 in both host and peripheral modes, although peripheral-mode support in the current driver is very basic.

Source code

• USBDriver, EHCIDriver and OHCIDriver are all built by the mixed/RiscOS/Sources/HWSupport/USB/NetBSD component in CVS.
  • The build folder contains the RISC OS module frontends and the makefiles, while the dev folder contains the bulk of the mostly unmodified NetBSD code.
    • build.c.ehcimodule, build.c.ohcimodule and build.c.usbmodule provide the frontend to the EHCI, OHCI and USB modules, respectively.
    • build.c.port is a common file shared between all three modules that helps bridge the RISC OS and NetBSD worlds.
  • build.c.usbkboard and build.c.usbmouse are part of USBDriver and provide RISC OS frontends to NetBSD’s USB keyboard & mouse support
  • build.c.ehcihal, build.c.usbhal, build.s.halheap and build.s.porthal are only used by the HAL build of the modules
  • The machine and sys folders contain various headers that are required.
  • The code also relies upon various other NetBSD-derived header files that are supplied by the internet stack (mixed/RiscOS/Sources/Lib/TCPIPLibs)
• MUSBDriver is built by the mixed/RiscOS/Sources/HWSupport/USB/Controllers/MUSBDriver component in CVS.
  • The code depends upon header files provided by both the main USB drivers and the TCPIPLibs component.

RHENIUM

Rhenium is the codename of one of the projects that Castle/Pace/Tematic worked on. In the context of the main USB drivers, specifying -DRHENIUM as part of the options line, CFLAGS and CMHGFLAGS (i.e. -options CFLAGS="-DRHENIUM " -DRHENIUM CMHGFLAGS="-DRHENIUM ") enables code which allows the EHCIDriver and OHCIDriver modules to utilise EHCI & OHCI controllers that are exposed by the HAL USB API (ordinarily, the modules only look for certain PCI devices).

The MUSBDriver module does not need the RHENIUM flag specifying, as it uses the HAL API by default.

Debugging

Debug versions of the modules can be built by adding the following to the -options strings:

Debug output is handled by the DebugLib library; check the module’s initialisation to make sure a suitable output device is in use. The USB modules can produce a large quantity of debug output, often from within interrupt handlers. A device which provides low-latency output and works correctly with interrupts disabled is therefore desireable (e.g. the DADebug module).

Debug commands

When debugging is enabled, each module provides a few extra *commands. Check the *help text or the CMHG files for details.

Debug logging level

The debug level can be altered at runtime via *commands, or set at load time by altering the module’s initialisation function. Generally speaking, if the debug level is above 10, you can expect to receive a lot of output.

Internal API

TODO – This is probably out of date since the EHCI code was updated to the latest BSD version.

The USB hardware drivers register themselves with the main USB module by using the USBDriver_RegisterBus? SWI. The hardware driver supplies the USB module with a pointer to its usbd_bus struct (see NetBSD.dev.usb.h.usbdivar), and the USB module responds with a pointer to its device struct (see NetBSD.sys.h.device; not to be confused with the HAL device struct!)

Presently the only purpose the device struct services is to allow the USB modules to deregister themselves with the USB driver on shutdown. All communication from USBDriver to the hardware drivers is done via function pointers contained in the usbd_bus struct, and all communication between the hardware driver and the USBDriver is done via SWI calls.

Notes on specific function calls

splusb(), splx()

These functions in *.c.port are used by the NetBSD sources to disable & restore interrupts. Note that splusb() is actually #defined to splbio().

tsleep()

This function in *.c.port is used by the USB drivers whenever they want to block waiting for an interrupt-triggered event to occur (e.g. completion of a USB transfer)

malloc_contig(), free_contig()

These functions in *.c.port use the PCI module to allocate & free noncacheable, nonbufferable blocks of memory suitable for use as DMA buffers. The PCI module ensures that only contiguous physical pages are used, greatly simplifying the process of setting up DMA transfers.

HAL build

The USB drivers can also be built as a set of static libraries suitable for linking with a HAL implementation. The main reason for doing this is to simplify the task of implementing the HAL keyboard API that RISC OS uses to perform the keyboard scan on boot. The HAL build of the libraries differs from the regular module build in several ways:

• The USBHAL preprocessor directive is defined, to allow the code to identify the build
• All C files include the NetBSD.dev.usb.h.usbhal header file. Ordinarily this header does nothing, but with USBHAL defined the header provides the following:
  • It uses a __global_reg directive to prevent the compiler from utilising sb as a general purpose register
  • It provides the definition of the usbhal_ws struct which is used to store the static data required by the drivers (regular global/static variables won’t work, as the C compiler won’t understand where to store them)
    • Since the above structure is stored inside the HAL workspace pointed to by sb, a USBHALWS macro is provided to obtain a pointer to the structure.
  • There is also the OSentries macro for any code that needs to call one of the OS entry points
  • It also provides prototypes for the main USBHAL_* functions that the HAL uses to interface with the drivers/keyboard scan code
• There is no mouse support, and the keyboard support has been stripped down to the bare minimum needed to support the boot-time keyboard scan
• A heap implementation (based around the OS_Heap source code) is provided, in NetBSD.build.s.halheap. The USB drivers use this to allocate all of their memory.
• Drivers operate in a mode designed to reduce their memory footprint, e.g. the EHCI driver uses a smaller frame list size. This makes it possible for the drivers to operate inside the small amount of noncacheable workspace that the OS provides to the HAL.
• There’s no support for detecting USB controllers located on the PCI bus. Only the RHENIUM-style HAL USB API is supported.

The HAL build of the drivers is built automatically by the “export libs” build phase, whether the HAL requires the drivers or not.

For an example of how to implement the HAL build of the drivers, see the OMAP3 HAL, specifically OMAP3.s.KbdScan.