Major operating systems like MS Windows, Linux distributions, UNIXes, BSDs and Solaris include full support for USB 1.1 and 2.0 as well as drivers for various host controllers. This is not surprising as some OS vendors contributed to USB development, and the specification has been available for some time.

Among experimental and academic OSes like Haiku, GNU Hurd and Minix, only Haiku includes full USB support. Neither of the two micro-kernel based systems (Hurd, Minix) include USB support, this makes HelenOS’s USB implementation a trailblazer.

HelenOS was started as a student software project in 2004 with the aim to build a portable microkernel operating system. The main goal was to create lightweight kernel supporting several different architectures with clean design and implementation.

Since then HelenOS has been used as a base platform for several bachelor and diploma theses. Apart from its microkernel nature the reason for using HelenOS for further development and research is its clean design and small size. At the beginning of 2011, over 20 students were participating on HelenOS as a part of their theses or other projects.

From the beginning, HelenOS was developed with portability in mind. Although the number of supported architectures is high (AMD64/EM64T (x86-64), ARM, IA-32, IA-64 (Itanium), 32-bit MIPS, 32-bit PowerPC and SPARC V9) the kernel is still relatively small and userspace contains only minimum of architecture specific code. USB was tested and developed on IA-32 and AMD64 architectures but the userspace library and kernel layer hides the architecture dependent ‘stuff’ and porting USB support to other architectures shall not create any unexpected problems.

The microkernel nature of HelenOS means that vital services the operating system provides are not part of kernel but are rather provided by userspace tasks. There are separate tasks for handling file system service, for networking or for drivers management. Most of these services are used transparently. For example, the fact that call to printf is actually translated to a call to virtual file system service from where it goes to console service that actually prints the string is hidden from the programmer and the semantics of printf does not differ at all from a monolithic OS. Knowledge of these services is not needed for understanding and developing USB drivers. There are exceptions, though.

First one is devmap — device mapper — service that creates representation of hardware and virtual devices in a file system. It takes care of the /dev directory that is somehow similar to the directory found in Unix systems.

The other one is devman — device manager — service that controls startup and communication between device drivers. Understanding this service is vital for writing device drivers for HelenOS and will be described in following section in more detail.

However, before describing it, several notes have to be made about inter process communication in HelenOS in general.

Communication between tasks is an important part of any general purpose operating system. And it is a vital part of a microkernel design. This section will be an overview of inter-process communication in HelenOS. Please note, that the term inter-process communication — IPC — is used even in microkernel environment where processes are usually called tasks.

HelenOS is based on asynchronous IPC. That means that when an application sends a message, the kernel takes care of the delivery but does not block the sender and the sender retrieves the answer by another request to the kernel.

The advantage of asynchronous communication is that the task can do something useful when waiting for the answer instead of being blocked in the kernel during some IPC system call. Also, it is easier to create an illusion of synchronous processing when asynchronous API is available than vice versa.

The disadvantage is that programming in an asynchronous way is more complicated. For servers accepting connections from more clients, asynchronous processing usually ends with registering of callbacks when some message is delivered and the code gets complicated.

In HelenOS, this disadvantage was bypassed by introduction of fibrils and asynchronous framework.

A fibril is a userspace cooperatively scheduled thread. Kernel has no knowledge of a fibril and the fibrils are backed by a real (i.e. kernel) thread. The scheduling of fibrils is cooperative and happens usually when asynchronous IPC operation take place.

The asynchronous framework is a set of C functions (part of HelenOS libc) that makes an illusion of synchronous IPC in order to allow simpler implementations of services. The main idea is simple: IPC will be asynchronous and each client connected to the service will be handled in a separate fibril where the communication would look like a synchronous one. The synchronous illusion is created by the framework. The framework keeps track of the fibrils and does the callback registration for them. When a fibril executes a pseudo-synchronous operation, the framework uses the asynchronous version of the operation and then schedules another fibril. When the reply arrives, the framework schedules the original fibril and for the programmer it looks like a return from a function.

This way the programming of services looks more natural and the asynchronous advantages are not lost. It also makes the kernel simpler. The same thing can be achieved using real (kernel backed) threads but then the kernel would need to keep track to which thread the message belongs. Now, the message is addressed to the whole task and the framework ensures that it is delivered to the right fibril.

So far, IPC was described in general terms such as message or response. HelenOS uses its own terms for some actions and it is necessary to know them in order to understand API documentation.

Probably the most confusing name is phone. A phone represents an open connection to some other task. Unlike in real life, these phones are unidirectional and only one side can initiate a message sending.

The message sent over the phone is called a call. The receiving party of the call eventually answers it by sending back a reply. A typical call consists of 5 integer arguments where the first argument is a method number describing action to be taken by the receiving party. An answer call also takes such arguments but the first argument is treated as a status code whether the action was successful. There are several special calls that are intercepted and preprocessed by the kernel. One of them is a hangup call that terminates the connection. Another group of such calls are data transfer calls that are used to transfer larger amount of data. Using a special call it is possible to create a callback connection that reverses the direction of the phone. This call reverses the normal connection scheme ‘I want to connect to you’ to ‘Do you want to connect to me?’.

Last two specials calls are a duplication request and a forwarding one. The first one duplicates already opened connection which is useful for example to allow parallel IPC between two tasks. The second one forwards an incoming call to another task. This functionality is crucial for naming service to forward connections to respective services.

When a task starts, it has only one opened phone connected to a naming service. This server remembers connection to other services and by duplicating and forwarding the connection allows other tasks to connect to them.

This scheme means that kernel itself has to know only about the naming service. Each task will got the phone to it and services will make a callback connection to register themselves for other tasks while clients will ask the naming service to be forwarded to other services.

Drivers in HelenOS are implemented as standalone tasks in userspace that require only minimal kernel intervention. This is in great contrast to monolithic kernels where all drivers are part of kernel and are living in the same address space. In HelenOS, each driver is a separate task that communicates with others through IPC. It seeks kernel assistance only for privileged operations, such as interrupt handling.

Although the idea of having all drivers in userspace exists since the beginning of HelenOS some drivers are actually part of the kernel. Some are there because they are needed by kernel. For example, a driver for AT keyboard is needed for kernel console. Some are vital for the boot phase and their move into userspace would be too complicated (e.g. ACPI reading). And finally, it is still possible to find traces from the first versions of HelenOS when total separation of drivers (i.e. their move into userspace) was not possible (e.g. because it would complicate development too much).

The framework itself consists of two parts. The first part is a the device manager service that is responsible for starting the drivers and for controlling their life-cycle. The other part is a libdrv library that is used by the drivers and that encapsulates communication with device manager.

Each driver is a standalone executable program that controls all instances of a certain device type. For example, when there are two USB keyboards attached to the computer, they will be both controlled by the same task (i.e. the same running instance of an executable file).

The device is attached to the driver by the device manager when some bus driver detects new device and devman decides that the driver is suitable for controlling the new device.

The description so far missed any information on how applications communicate with the drivers or vice versa. This is done through so called interfaces. For an application, the interface of the driver describes its capabilities and way how to query the device. From the driver point of view, interface is a set of callbacks the driver must implement.

Obviously, there must be IPC behind these interfaces. The application talks with the driver through IPC that is wrapped on both sides into higher-level functions. For applications, these functions are sometimes part of libc or specialized libraries. On the other side of the IPC, drivers use libdrv that wraps the call reception into callbacks to C functions. Nevertheless, if you are planning to add you own interface, you will need to implement the IPC layer by yourself because HelenOS misses any automated stub generation.

This chapter was a mere overview or a refreshment course if you wish. If you feel uncertain in some aspects it is recommended to learn more about HelenOS prior trying to implement USB drivers.

Below is a list of recommended sources

USB is a technology used for connecting peripherals to host computer. Its main advantages are simplicity of usage for end users, pretty good scalability (in terms of number of simultaneously attached devices) and a choice of possible transfer types that accommodate requests of diametrically different devices. The USB defines the following aspects (most of them will be mentioned later in this chapter):

The following sections will describe parts that are most important for authors of device drivers. They will not include description of low-level aspects, such as electrical current settings or sizes of mechanical plugs.

The acronym USB is used in two slightly different meanings in the following text. First, as a common prefix (e.g. USB device), second in its original meaning, describing the bus itself (when the word ‘bus’ is used, it will always refer to the Universal Serial Bus unless explicitly stated otherwise).

USB uses a tree-like physical bus topology. In the root of the tree there is the host computer with a hardware chip — host controller — controlling all communication over the bus. All communication requests of device drivers are directed to the driver of the host controller that schedules them and then sends them to the USB ‘wire’. The host controller provides several ports to which devices are connected.

USB devices come in two flavors. First, there are functions — these provide actual functionality and create leaf nodes in the bus topology. Example of a USB function is a printer or a keyboard. The other kind are hubs that create branches on the bus and to which other devices might be connected.

Hubs provide means to attach more devices to the same bus. The attachment place is called a port (typical hubs for PCs has about four ports). Actually, each hub has two different kinds of ports. First, there is the upstream port through which the hub is connected to a parent device (i.e. the predecessor in the tree) and then there are several downstream ports through which other devices are connected. The host controller must always provide at least one port to allow device attachment. Typically, the host controller provides its own hub, called root hub.

Although physically, the topology is a tree rooted in the host controller, addressing of the devices uses a flat structure (see figure below) and under certain abstraction, hubs can be viewed as transparent splitters that add no logic to the bus.

Each device connected to a host controller receives a unique address (a positive integer) and reacts only to communication that is targeted to it. Before the device receives this address, it listens on the default address (number zero). To prevent situation when more devices would listen on the default address simultaneously, each hub must provide means to disable communication forwarding to certain ports (USB terminology says that hub does not signal on given downstream port).

USB was designed to be as flexible regarding device configurations as possible. Because of this, each device can provide several configurations. Each configuration may provide completely different sets of features but practically almost all common USB devices have only single configuration.

Each configuration can provide one or more interfaces. The interface provides the actual functionality of the device. For example, USB printer provides the printing as an interface. Some devices may provide more than one interface. For example, a digital camera may provide an interface for direct communication with the camera (usually via vendor drivers) and, as a fallback, a mass-storage interface that can be used to download photos when the specialized drivers are not available.

Each interface can have several alternate settings than change device capabilities at interface level. For example, network card may offer several alternate settings using different sizes of data packets.

The actual communication with the device happens through endpoints. Each endpoint belongs to a single interface and represents a communication ‘gate’ to the device — USB uses the term pipe to describe an abstract connection between device driver on one side and the device on the other one. Endpoints are unidirectional (either in or out) and have several attributes that must be obeyed by the driver.

A special endpoint — control endpoint zero (sometimes default control endpoint) — is present on each device and is used for configuration purposes and for standard requests (e.g. for querying the device for generic capabilities).

The USB defines how data that are supposed to be sent to (or received from) a device shall be encoded and treated prior to their sending over the wire. This overview skips the ‘electrical’ aspect of the communication and starts with abstraction that the host controller has means to send a stream of bytes to the wire.

Communication over the bus uses data packets that encapsulates the actual payload and some service data. The service data include target address, endpoint number, packet type and data needed for packet integrity checks.

Before moving on to describing packet types, it is necessary to mention transfer types. In order to allow devices with different transfer requirements (e.g. web camera that supplies a continuous stream of data vs. keyboard with few bytes several times minute) transfers over the bus happen in four different types.

When a device driver wants to send data to the device or accept some data from the device (the device cannot initiate the transfer under any conditions), it gives the payload to the host controller together with information about target device (address) and endpoint. It must also provide information about transfer type and data direction. The host controller then encapsulates these information into two packets. The first packet informs about data direction while the other transfers the actual data. For incoming transfers, it actually reserves bandwidth to which the device can send the data.

This protocol is roughly the same for bulk, interrupt and isochronous transfers. Control transfers are a bit different because they have a special preambule — a setup packet. The setup packet contains commands that might change the device state and this packet might be optionally followed by a data phase. Notice that control transfers are the only ones that are actually bidirectional (because the setup packet is always outgoing, while the data phase could be either in or out).

In previous sections querying USB device for its capabilities was mentioned. This sections will describe this querying in more detail.

Each USB device must provide several data blocks, called descriptors, describing its configuration and capabilities. Some descriptors are device dependent while others are generic for any USB device.

The roughest description of a device is provided in a device descriptor. It holds information about device vendor, device class (see below), number of possible configurations and several other details.

Each configuration is then described by a configuration descriptor. This descriptor also contains the number of interfaces the configuration provides. Each interface is then described by an interface descriptor. The interface descriptor specifies to which class the interface belongs and how many endpoints it specifies. Unsurprisingly, each endpoint is described by an endpoint descriptor. This descriptor defines attributes of the endpoint — data direction, transfer type and endpoint number
[ When you write a device driver, you ought to know what endpoints the device shall have. The endpoint descriptor is then used to merely map driver expectations to correct endpoint number. ]
.

The descriptors can be viewed as a tree, where device descriptor is the root node that has several descendants — configurations. Each configuration then groups interfaces and endpoint descriptors are leaves. Device may provide its own descriptors (e.g. vendor specific ones) that may stand aside of this tree or be part of it (then they are typically inserted somewhere between interfaces or endpoints).

Although logically the descriptors form a tree, the device usually returns them in a serialized manner. For example, interface and endpoint descriptors can be retrieved only as a part of a configuration descriptor they belong to. The ordering in the serialized form implies the logical tree it represents. The USB descriptor tree figure shows the logical descriptor tree, circled numbers next to items of configuration subtree denote ordering in the serialized descriptor.

USB was designed with flexibility of offered functionality in mind but to prevent total chaos, devices (or rather their functionality) were divided by common attributes into so called device classes. Each class deals with devices of certain kind, e.g. HID devices, printers, scanners, audio or a special vendor class for any device that would not fit into any other one. Some classes define subclasses for fine-grained resolution (e.g. HID class offers subclass for keyboards and mice).

The class is reported as a part of device and interface descriptor. That is because single physical device may provide functionality of several classes simultaneously, depending which interface the software communicates with. In such cases the class reported through the device descriptor is a special value with meaning ‘no class, see interface’.

USB was designed with possibility of hot-plugging and thus it has to have well defined actions when a new device is added. The following is a simplified sequence of what all the involved drivers and devices must go through. The setup is that new device is attached to some hub, that is already initialized and configured.

The new driver is then told the address of the device and it is up to it to configure and finish the initialization of the device.

As stated above, the sequence is simplified and due to errors in devices (not all USB devices obey the specification exactly) some steps (e.g. setting new address) have to be tried several times or in specific ordering.

Definitions common for any USB device or host controller are in libusb. This includes structures for device descriptors and basic constants.

This library is used by all other USB related libraries and thus you have to link with this library.

More details can be found in Common USB library.

All USB device drivers are built above a common layer that provides abstraction over physical communication with a USB device. This layer is part of libusbdev and gives the programmer access to objects using the same level of abstraction as many USB specifications.

For example, the programmer uses object called usb_pipe_t to communicate with the device and do not have to care about actual USB transfers and transactions that are created on the bus.

Part of this library are also wrappers for standard device requests, simple parser of serialized descriptors or helpers for device polling.

This library is described in more detail in Writing USB device drivers.

According to USB specification, a host controller must create so called bus interface to allow unified communication from device drivers. The interface itself is described in the generic driver library but the implementation is up to the drivers. However, the functionality is similar for any host controller and thus a common library libusbhost exists.

This library provides helper structures and functions for keeping information about connected devices, about their endpoints or keeping track of free bandwidth.

For more information see Writing USB host controller drivers.

USB device for human input is self-descriptive in a way that each device describes which input controls it offers and how these controls are set. The parsing of such description is not a trivial task and because HIDs can be very specific, the whole parser and other helper functions were put into a separate library called libusbhid.

This library is expected to be used by any HID driver and more information about the parser and other functions can be found in Writing HID drivers and subdrivers.

Changes to kernel include temporal workaround for missing physical memory allocator and a short sleep system call.

Current version of HelenOS has no means to allow userspace tasks allocate physical memory with given attributes. A task can create new address space area (continuous block of pages) but has no means to specify where from the physical frames shall be allocated. That could lead to troubles with devices reading or writing data from a memory. Such devices may use only 32-bit addressing and it is not possible to use frames with addresses above 4GB.

Such allocator is currently being developed by another Software project team (NIC framework) and the authors decided that it is not necessary to duplicate this work. Thus only a simple system call for retrieving physical address was added. Obviously, this could fail on machines with more than 4GB memory but that would mean that someone was able to use all 4GB of memory which is hard to imagine with available end user software in HelenOS.

Memory caching was also disabled to prevent inconsistencies in communication between a device and a driver.

The granularity of fibril sleep in userspace was not sufficient when executing operations on I/O space registers. These operations must be separated by a very short delay that was not possible to ensure with existing libraries. The kernel does not export the real time precisely enough and thus a simple actively waiting system call was added.

The question whether to use a system call or some userspace routine is opened for further discussion among HelenOS developers.

During development, several problems in devman were found. These were reported upstream and repaired in the mainline.

Several minor improvements were applied only in USB repository. These might be either cherry-picked or merged together with the whole USB subsystem.

The console server is responsible for switching virtual terminals and forwarding keyboard events to them. console was extended to allow automatic detection of hot pluggable devices, such as USB keyboards.

The detection of hot-plug HIDs is done in following manner. The respective device drivers shall detect the device, initialize it and create exposed DDF function for it. Keyboard device drivers shall add this function to keyboard device class while mouse devices to the mouse one.

The console periodically checks directory with these classes and tries to connect to any new device that appears there.

A special workaround was added to allow proper connection destruction when the driver stops sending new events (typical situation for device unplugging).

It is expected that console would undergo a major rewrite in near future that would simplify its communication with device drivers and would probably lead to creating a special service for processing of events from human input devices.

Such server might take care of some functionality currently handled in device drivers. For example, automatic key repeat is handled in the device driver. The design of the driver would be cleaner if it would only need to send ‘key press’ and ‘key release’ events and leave repetition on the server. The server may also take care of layout switching, another functionality that is now duplicated in drivers.

Writing the HID server would probably require rather drastic changes to several components of HelenOS and was beyond scope of the USB project.

The existing PCI driver was extended to allow interrupt enabling and to allow drivers of attached devices write to PCI configuration space.

Unfortunately, similar changes were done by the NICF team with almost identical API. However, it is expected that resolving the conflicts would be trivial.

The role of the host controller driver task is to provide interface for USB device drivers. The interface is independent from different host controller implementations. Moreover, it contains functionality that is shared or not specified by host controller specifications.

The host controller driver task interface is specified in <usbhc_iface.h> provided by libdrv. The interface provides two sets of functions, the first set manages state of USB bus and it is a part of USB bus driver, the other set provides access to communication capabilities of the underlying host controller. While it is possible to use this interface directly in applications and device drivers, the suggested way is to use USB bus driver frontend implemented in the libusb family of libraries.

UHCI design guide mentions that UHCI was designed with hardware simplicity in mind. It means that great deal of functionality is left to be implemented by the driver software. On the other hand, it also means that there is a considerable freedom for OS developers in the driver’s implementation.

OHCI host controller is a rather complicated device and `the design goal has been to balance between the complexity of the hardware and software’
[OHCI specification, ftp://ftp.compaq.com/pub/supportinformation/papers/hcir1_0a.pdf, p. 1]
. It supports more functionality in hardware, but also provides less freedom for system developers.

OHCI root hub and its workflow is much similar to the normal USB hub (see USB hub driver). Therefore only a simple layer between the host controller driver and the hub driver is needed. This layer processes hub drivers' requests and ‘emulates’ function of the normal USB hub. It is embedded into the OHCI driver. This implementation is recommended by the OHCI specification.

Hub driver implementation is in uspace/drv/usbhub. The driver first initializes structures for USB device drivers library, sets the log level and calls \function{usb_driver_main}. When a new hub is registered, the driver initializes its structures and starts its fibril. This polls the hub on the interrupt pipe and handles any detected changes.

The HID class comprises devices that allow users to control computer systems. Typical examples are keyboards, mouses, joysticks, various buttons, switches, data gloves, etc. Some of these devices also provide some sort of feedback to the user (displays, audio feedback, etc.).

The USB HID device class definition
[http://www.usb.org/developers/devclass_docs/HID1_11.pdf]
specifies how such devices should be implemented and how a HID class driver should communicate with them. As various HID devices may have very different requirements, this document defines a generic and extensible protocol called Report protocol (see Report parser).

All USB HID devices share the same way of communicating with host (using the Interrupt In pipe) and the same format of data (Reports). Thus only the data interpretation is what makes the devices distinct from application point of view.

This allows separation of handling the HID device on the lower level from the data interpretation and processing on the higher level. There are two ways to achieve this:

Both approaches have their pros and cons which will be discussed in the following paragraphs.

The first approach (separate processes) is more clean from the design point of view — different tasks are done by different processes — all in the spirit of a true microkernel OS. Adding a new driver for some special device would be also easier, as the existing code would not have to be changed. On the other hand, there would be some non-trivial obstructions to overcome. Firstly, the report parsing could not be done inside the main HID driver as there would be no way of sending the parsed report over to the child driver processes. It would have to be serialized, but then it would be easier (and with less IPC involved) to just send unparsed reports over to the child drivers and let them do the parsing. However, in such case the idea of separating common HID logic from device-specific would not be fully accomplished. Another obstacle is the distinction between various types of devices and the need to associate drivers with devices. With DDF (see Device driver framework in HelenOS) in place, it would be necessary to create some sort of match IDs for each device, based on the contents of the Report descriptor. As this may be fairly complex, it might be quite complicated to create universally functional match IDs.

The second approach (one process handling all kinds of HID devices) would make it harder, or at least less straightforward, to add drivers for new devices as it would change the code of the whole driver which would then need to be recompiled and restarted. However, with well-defined API for the ‘subdriver’ modules it would not be very hard to create such code and it would be also quite easy to communicate directly with the device in case of need. The Report parsing may be done in the main part of the driver, so that the subdrivers receive parsed data and can do only the required interpretation. Another advantage is the special handling of Boot devices — e.g. falling back to the Boot protocol in case there is no subdriver that understands the report.

Therefore, the autors decided for the second approach, creating one complex HID driver which handles all kinds of devices but has a clean subdriver API.

The USB keyboard subdriver provides means to communicate with and use any standard-compliant USB keyboard. It takes care of device initialization, polling the device for Input reports and relaying parsed data to applications (actually only to the console), maintaining the state of locks (Caps Lock, Num Lock and Scroll Lock), synchronization of LEDs with the locks and auto-repeating of keys.

This subdriver is used either if the Report contains Collection with Usage Keyboard from Usage page Generic Desktop (for details about Collections and Usages see section Report and report descriptor parsing; detailed information are also in the USB HID class definition, part 6.2.2.6, Usage pages are listed in HID Usage Tables
[http://www.usb.org/developers/devclass_docs/Hut1_12.pdf]
), or Boot class keyboard for which there was no other subdriver matched.

The subdriver is located in /uspace/drv/usbhid/kbd/. The main structure, representing keyboard is usbhid_kbd_t, which uses the generic HID device structure (see above) and holds keyboard-specific information, such as currently pressed keys, active locks or information about auto-repeating of keys (see <usb/hid/kbd/kbddev.h>).

When the control over device is handled to the subdriver (by calling usb_kbd_init() from the HID core initialization function usb_hid_init()), it creates a new usbhid_kbd_t structure and initializes it. The initialization consists mainly of setting some default values, preparing buffers, creating a fibril for key autorepeat (see <usb/hid/kbd/kbdrepeat.h>) and creating a DDF function for the keyboard. It also sets the LEDs on the keyboard to the default value (Num Lock turned on, other turned off) and sets the Idle rate
[Rate at which the device would periodically report events even if there are none new events ready.]
to 0 (i.e. infinity — the keyboard will only report when a new event is available).

After receiving a report (via callback usb_kbd_polling_callback()) and parsing it, the subdriver evaluates which keys have been pressed or released, updates the state of modifiers and lock keys and notifies applications connected to the driver. In fact, currently the driver only communicates with the console to which it sends new key events. In order for the console to be able to connect to the HID driver controlling the keyboard device, the keyboard subdriver creates a DDF function (named keyboard) and adds it to the keyboard class. The console periodically checks this class for new functions and tries to create a connection to such function (i.e. driver). The connection from the console is handled in the \func({default_connection_handler()}) function, defined in kbddev.c.

The mouse subdriver (located in /uspace/drv/usbhid/mouse/) takes care of HID devices providing mouse functionality. It is used either if the Report contains Collection with Usage Mouse from Usage page Generic Desktop, or as a fallback for any device declaring support of mouse Boot protocol.

In the initialization routine (usb_mouse_init()) it creates the main mouse structure (usb_mouse_t) and initializes it by creating buffer for pressed buttons and creating DDF function (and adds it to class mouse so that the console will try to connect to this function as well).

When a new event occurs (usb_mouse_polling_callback()), the subdriver retrieves values for X and Y axes, for the wheel and for buttons. The movement in X and Y axes together with the buttons are sent to the console (if there is one connected) as mouse events. The wheel scrolling is treated as pressing arrow keys (up or down; actually one move of the wheel is interpreted as 3 presses of the corresponding arrow key).

Multimedia keyboards often have separate interface for multimedia keys. Though this is not specified by any standard, most of vendors use such separate interface and report the keys as Usages from the Consumer Usage page. This allows for a fairly generic way to handle these keys. Therefore, a specialized subdriver for these keys was added to the USB HID driver in HelenOS (it is located in /uspace/drv/usbhid/multimedia/).

This subdriver is initialized for any interface on which the device’s Reports contain Usages from page Consumer. Currently, there is no use for these keys in HelenOS, but in the future it should be easy to add mapping of these Usages to any HelenOS keycodes (by altering the usb_hid_keymap_consumer static array in keymap.c) or to process them in other way (by modifying the usb_multimedia_polling_callback() function).

In order to allow simple and straightforward extensibility of HID device support, a generic HID subdriver was implemented. This subdriver is initialized as a fallback for each device (more precisely for each interface) not supported by other subdrivers and additionaly for all supported devices (interfaces). Its main function is to provide interface for third-party applications to receive reports from the device.

It creates a node in the device tree (named hid) to which the applications may connect. The client interface is available in <usb/hid/iface.h> of libusbhid. It consists of four functions:

This implies that the application receives raw data from the device and must do all the parsing by itself. It was designed this way because of problems with sending structured data over IPC. They would have to be serialized but then it is easier just to send the raw data from the device. This is also the reason for the first two interface functions — getting the Report descriptor and its length — as these are needed for initializing the HID parser. The HID parser is part of libusbhid and is located in <usb/hid/hidparser.h> and <usb/hid/hiddescriptor.h>.

Because all USB drivers share some functionality (such as communication with their host controller), a common USB library exists. The library is located in /uspace/lib/usb, the actual library file is /uspace/lib/usb/libusb.a and the headers are in the include/ subdirectory. All functions, types and macros are prefixed with usb_ (or USB_) to prevent name clashes with other libraries.

When using the library, add /uspace/lib/usb/include to include path of your compiler. That way, you would be able to include libusb headers easily. Do not be tempted to add also the usb subdirectory directly because some files bear very generic names which could lead to confusion with headers from other libraries. Below is an example of Makefile settings when linking with libusb and part of C source that includes the base USB types and base definitions of HID class.

Individual functions will be described in chapters regarding writing USB device drivers and writing host controller drivers. However, for detailed explanation, it is recommended to consult reference documentation (or, ultimately, the source codes). Below is an overview of functionality available in libusb.

Currently, HelenOS lacks any central mechanism for logging system events (such as Unix syslog). To ensure some kind of forward compatibility, it was decided that all USB related drivers will use the same mechanism for reporting errors and for logging device events. The whole mechanism is actually only a set of functions for logging events backed by writing these messages to screen and to a disk file.

The idea is that all events the driver wants to record (and inform the user about) shall be reported via these functions. That ensures that all drivers use the same format which shall simplify debugging. The logging itself is done through a single function that takes logging level as a first parameter (see below for levels description) and remaining parameters are virtually passed as-are to a printf function for actual printing.

There are four levels for basic reporting. They are mostly designed for reporting errors with different severity levels. They are followed by several levels for debugging messages. The default setting for all drivers is expected to behave in following way: the four basic levels are always printed to the screen as they contain vital information and all levels are written to log file in the /log directory. Below is a list of logging levels with examples for their typical usage.

This section describes conventions used by existing drivers for creating device match ids. Match id consists of two parts — match score and match string. Only match strings will be discussed here because the score is a matter of each driver — how suitable it is for individual devices.

USB match strings uses formatting similar to query part of URLs. Each match string starts with usb prefix to separate match strings of USB devices from devices of other kinds. Individual (logical) parts are separated by ampersands & and for concrete values (e.g. driver for concrete version of a specific device) the format attribute=value is used.

The match strings are generated in usb_device_create_match_ids_from_device_descriptor() and usb_device_create_match_ids_from_interface() functions (sources in recognise.c). Below are several examples but the best way for creating driver match strings is to see the actual output from usbinfo application of a concrete device.

Below is a dump of match strings generated for mass storage interface (hence the interface part) of Kingston flash disk. The match strings are sorted by their score in decreasing order. Note that almost all numbers are printed in hexadecimal but always with standard 0x prefix for emphasis.

This section describes implementation details in interfaces used for communication between USB drivers. The communication is done purely using interfaces provided by the Device driver framework. There are two interfaces for USB drivers: one for host controllers and one for function devices. Their description is followed by explanation of how the USB device finds the host controller (driver), how it is connected to the host controller and how it learns its own USB address.

The virtual host controller is a userspace application that provides two different interfaces. The first interface is towards USB device drivers where the program offers the same functionality as must be provided by any USB host controller driver in HelenOS. The second interface is for virtual devices and can be thought of as a simulation of the bus. The application can be also logically divided into two parts — hardware simulator (more or less) and a driver for the simulator.

Unlike real (i.e. hardware) host controllers, the virtual one does not work with transactions but only with transfers. Although originally the host controller split the transfers into individual SETUP, OUT and IN transactions, the idea was later abandoned because it complicated both the virtual host controller as well as the virtual devices. This can be thought of as a major difference but this difference is in no way propagated to the device drivers and simplifies the implementation a lot.

Part of the host controller is also a root hub that is driven by the hub driver. The simulated devices then appear as being plugged into the root hub.

Virtual USB devices are userspace applications that simulate a life of a real USB device. When they are started, they connect to the virtual host controller and announce their presence. The root hub then simulates a change on the port and it is up to the hub driver to inform the device manager that new device was discovered. Later, virtual host controller would send transfers to the virtual device that shall answer them.

The idea is that the application simulating the real device would contain some state automaton describing the status of the device. The status could be changed by two ways: by itself or by the driver. For example, human interface devices would change by themselves, thus simulating human interaction and the driver only asks for current status. But simulator for mass storage would keep list of blocks and would change their content by commands from the driver and would not create any activity by its own.

The actual communication is done through IPC. The virtual device initiates the connection by connecting (via devman) to the virtual host controller that is expected to have always the same device path (/virt/usbhc/hc). The device then asks for a callback phone to allow host controller to initiate transfers. This way, the master-slave nature of USB is preserved even on the virtual layer.

The virtual HID is currently the only application that simulates a USB device (except for the root hub in the virtual host controller). Its main purpose is thorough testing of the HID parser that has to deal with complex Report descriptors.

The application was designed to be easily extensible. It is easy to add a new USB interface with a special report descriptor. Each interface then defines callbacks for data setting and retrieval and a special callback for simulating actions.

The application is located in uspace/app/vuhid and is launched with vuh command, parameters being names of interfaces the new device shall have.

If you want to extend the virtual HID with your own interface, probably the easiest way is to copy the existing interface and change it to your own needs. The simplest one is the one for boot protocol keyboard that is located in uspace/app/vuhid/hids/bootkbd.c. The interface is represented by vuhid_interface_t structure, the individual attributes are described in the reference documentation. Once you prepare this interface, you add it to the list in ifaces.h and in ifaces.c.

You can then launch your new interface by specifying its name on the command line when starting the vuh application.

This section and the next one will provide a high-level overview of the framework for writing device drivers. The following section will then guide you through the low-level details using simple mouse driver as an example.

This section will describe the API that was described in previous sections. The initialization is described below through an example for USB mouse because it is more understandable that way.

This section will guide you through the process of creating a very simple, yet functional, mouse driver. Because the focus of the chapter is the USB part of the driver, we will omit how the retrieved data of the mouse would be used to actually move some pointer around the screen.

The mouse driver is part of the HelenOS distribution and used file paths refers to its actual placement within HelenOS source distribution.

The USB specification describes several control requests each device must respond to. These requests are used to query status of the device or for retrieval of device descriptors. These requests are very common and wrappers for them were created. The wrappers have declarations in <usb/request.h>, for parameters description consult the reference manual.

For most of standard USB descriptors there exist C struct counterparts in libusb. Generic structures (used by all devices) are stored in <usb/descriptor.h>. For class-specific descriptors, see corresponding files in classes subdirectory.

If you will create your own descriptors (e.g. vendor specific), do not forget that compiler will typically try to align the structure and adding __attribute__(packed) is necessary (although non-standard, this attribute is supported by most compilers).

It was already mentioned that USB descriptors can be viewed as a tree but they are sometimes stored in a serialized manner. For example, configuration descriptor is followed by interface and endpoint descriptors and there is no way to retrieve these directly. A simple parser was created for deserialization purposes.

The parser tries to be as generic as possible and thus the interface it provides is somewhat terse. It operates on byte array and offers only functions for finding first nested descriptor and for finding next sibling (i.e. descriptor on the same depth of nesting).

The parser expects that the input is an array of bytes where the descriptors are sorted in ‘prefix tree traversal’ order (see descriptor tree figure). Next, it expects that each descriptor has its length stored in the first byte and the descriptor type in the second byte. That corresponds to standard descriptors layout.

The parser determines the nesting from a list of parent-child pairs that is given to it during parser initialization. This list is terminated with pair where both parent and child are set to -1.

The parser structures and functions are stored in <usb/dp.h>. The parser itself uses usb_dp_parser_t structure. Currently it only contains array with possible descriptor nesting (usb_dp_descriptor_nesting_t). The data for the parser are then stored in usb_dp_parser_data_t, the arg field is intended for custom data.

For processing the actual data, two functions are available. The usb_dp_get_nested_descriptor() takes parser, parser data and pointer to parent as parameters. For retrieving sibling descriptor (i.e. descriptor at the same depth) one can use usb_dp_get_sibling_descriptor(). This function also takes parser and parser data as parameters. But it requires two extra arguments — pointer to the parent descriptor (i.e. parent of both nested ones) and pointer to the preceding descriptor. The mentioned pointer must always point to the first byte of the descriptor (i.e. to the length of the descriptor, not to its type).

There is also a simple iterator over the descriptors. The function usb_dp_walk_simple() takes a callback as a parameter. This callback is then executed for each found descriptor and it receives current depth (starting with 0) and pointer to current descriptor. For other parameters, see reference manual.

To ease writing of HID drivers and subdrivers, all the common functionality was separated into the libusbhid library, located in /uspace/lib/usbhid/. Its funcions may be divided into few logical units:

The easiest way to improve support of HID devices in HelenOS would be to utilize the available facilities provided by the HID driver and the HID framework (see above) and to write a subdriver for handling a particular type of device. This comprises two steps:

The subdriver source files must be then added to the HID driver Makefile in order to be compiled into the driver. When this is accomplished, the HID driver will try to match any device it is supposed to control, to this subdriver. All the callbacks will receive the HID device structure as the first parameter, i.e. they will have direct access to the data about the device, as well as the incoming reports (stored in the structure as well).

In case the options provided by the subdriver system are for any reasons not satisfactory, or if the implementor does not wish to leave the polling to the libusbdev library, it is also possible to write a whole separate driver for any kind of HID device, with the help of the USB HID library. In such case, the driver must specify the match IDs (see conventions) appropriately, so that it will be launched by the DDF.

A simple example is the mouse driver mentioned in the previous chapter.

EHCI brings support for high speed signalling on USB bus. If the ability to mix USB 2 and USB 1.1 devices on one bus is not required, it is fully possible to use USB 2 devices in the current state of USB support for HelenOS, once EHCI driver is implemented.

A host controller device is usually a PCI device, thus it is necessary to know its assigned vendor and product id. This device provides functionality for both host controller and root hub. EHCI shares status register and interrupts between host controller and root hub, thus it will need to emulate USB hub and handle USB requests using device register access. EHCI driver will need to initialize USB bus driver structures (usb_device_keeper_t and usb_endpoint_manager_t) as well as its local structures that can be found in EHCI specification in chapter 3.

Root hub function will be at the top of USB device hierarchy and it needs to implement usb_iface_t interface. This interface is defined in <usb_iface.h> in libdrv. It consists of three functions:

Host controller interface is defined in <usbhc_iface.c> in libdrv. Functions in this interface can be divided into two categories, the first one can be called USB bus driver back-end functions: * request_address is called when a new address for a new device is needed. * bind_address binds used USB address to devman device handle. This connection is used by the driver to get its USB address and by usb utilities to query devices based on drivers. * find_by_address provides information about device address to driver mapping. * release_address returns address requested by request_address. It may be caused by device initialization failure, or device unplugging.

All functions that manipulate addresses should be handled by usb_device_keeper_t in the EHCI driver.

These two functions should be handled by usb_endpoint_manager_t. As there is no per endpoint EHCI specific data structure, the driver does not need to add any special functionality to this calls.

The other part of usbhc_iface_t interface handles data transfers:

All these functions are similar. They need to setup internal memory representation of the requested transfer and enqueue this representation into internal schedule.

Using EHCI driver implementation mentioned in this chapter it will be possible to use high speed devices. It will not be possible use USB 1.1 devices connected to high speed hubs. This feature requires utilization of Transaction Translation features and more extensive changes to the USB framework.

Currently the HelenOS USB subsystem was tested on IA-32 and AMD-64 platforms. Any current PC should be able to use it, unless its USB chip fails to meet USB requirements specified by USB specification.

HelenOS can be downloaded either in form of source files or binaries. The easiest way to get HelenOS run is to download binary for your platform from official HelenOS web site
[http://www.helenos.org/]
(in most cases in form of bootable CD image) and depending on the form of the binary either use it as a machine image for target platform emulator or write it on a compact disk and boot the system from the CD
[Note, that at the time of writing this documentation the USB subsystem has not been merged into main HelenOS repository yet.]
.

To ensure you have HelenOS with the latest version of USB subsystem, you may want to download source files from repository of the project and compile them by yourself. It is recommended that you build the project on Linux system, as many tools used to build the project are much harder to use in other systems' environments.

First you need to download the sources from repository. For that you need to install a client for Bazaar, an open-source distributed version control system. Then just type in the console

for downloading branch of the HelenOS USB development team. This will download source files for whole HelenOS into helenos_usb. After that, switch to the new directory and run make.

A menu with build options will appear. Select preconfigured defaults for ia32 or amd64, disable SMP support and confirm to start the build. After the build the helenos_usb will contain ISO image of bootable CD with HelenOS image.iso.

Current version of HelenOS USB subsystem supports any USB 1.1 compliant device given that there is the right device driver in the system and it does not require isochronous data transfers (those are used mostly for multimedia devices, which are not supported in HelenOS). This includes USB hubs and human interface devices such as mice or keyboards. Subsystem is also able to recognize most other USB devices. However, without appropriate drivers for them it is not able to use them.

USB devices can be plugged at any time during the system run or even before. Most of them should be able to gracefully recover from unplugging.

This chapter describes USB related command-line tools available for users of HelenOS.

The device driver framework does not provide functionality for handling device unplugging. The USB drivers are almost ready when such support would be added.

The drivers use a heuristics that several consecutive failed attempts for communication with them means the device was removed by a user. The driver then tries to free all allocated resources.

Obviously, changes to the drivers would need to be made once the unplugging support is available. For most of the drivers, the changes would be rather trivial. Host controllers are not expected to be hot-pluggable devices and support for device unplug is not necessary.

There are many drivers that can be implemented such as driver for mass storage devices. It was the goal of the project — to create a robust platform for writing USB device drivers.

USB subsystem currently lacks support for isochronous transfers. These are multimedia transfers and there is no multimedia support in HelenOS. Thus the feature was not implemented as there was no suitable way to test it.

Implementation of this feature should include

The implementation would require changes to the current USB transfer scheduler. Current schedulers are not ready for time critical transfers and such needs are ignored.

Another field of future development is implementation of power management. HelenOS currently lacks any power management features. If it is implemented, it will suspend or resume particular USB devices or a whole USB device tree at once.

Suspending a device from power management task would require it to obtain device’s parent handle in the DDF tree and ask the parent to suspend/resume the device. Hub driver and UHCI root hub driver would implement a call to suspend/resume a specified device. They would also handle ‘suspended status’ port change — this is not implemented as currently there is no way a device could be suspended.

HCD is responsible for suspending entire bus and all connected devices. Implementation would require a suspend and resume call for HCD as well as implementation of these commands in HCD.

Support for more device configurations is not present at all (because hardware vendors do not use this feature much) but adding it is possible. The following changes would have to be done:

Support for alternate interfaces is implemented but was not tested. The framework always chooses the first setting and support for interface switching would involve following changes:

This section focuses on USB 2 and its influence on USB 1.1 drivers implementation. It discusses features of USB 2 enabled hosts that need to be considered by OS drivers developers.