Writing Device Drivers for HelenOS

What is a device driver?

The hardware an OS runs on can be modelled as a hierarchy of (peripheral) interconnects (buses) to which devices are attached. Each bus provides connectivity to devices or other buses. This hiearchy can be often represented as a tree (or directed acyclic graph), where inner (nexus) nodes correspond to buses and leaf nodes correspond to devices.

Needless to say this is just a model, meaning nothing is given a priori, the model can look differently depending on our choice. It is often not clear what is a device and what is not, where are the boundaries of a particular device, etc. Consequently, there is also no clear line between what still is a device driver and what is not.

Usually devices (or their drivers) have one or more of the following traits. When a system is coming up, it attempts to transitively discover all buses and devices connected to it. For each bus or device it selects the appropriate driver. The driver takes (complete) control of the bus or device and makes its services available to the system (to other drivers in case of a bus, to applications in case of a device). The driver abstracts away the details of a particular device model and provides an interface common to a class of devices (e.g. Ethernet adapter). The system often also virtualizes the device, providing concurrent access to multiple clients, but this can be done at a higher level, rather than in the driver itself.

Overview of Drivers in HelenOS

Device drivers in HelenOS come in two flavors, plain drivers and DDF drivers. Plain drivers originated before the Device Driver Framework (DDF) was created. They are simple servers which are started manually (from command line or from init task) and they reside in /srv. DDF drivers make use of the Device Driver Framework which takes care of starting them, attaching them to devices, etc. They reside in /drv.

Both kinds of drivers export their services to clients in the same way, as services registered with the Location Service. Each service has a unique name and it can be added to one or more categories. For a client it does not matter how a service is implemented, whether in a plain driver or in a DDF driver. This is an important design point.

DDF drivers are most useful for drivers that reside on busses that support discovery and hotplug (PCI, USB). Plain drivers are useful for implementing pseudo-devices. file_bd is an example of a plain driver. It implements a file-backed block device and it is started from the command line.

DDF (Device Driver Framework)

The Device Driver Framework (DDF) implements common functionality which is useful for most device drivers. It manages the device topology graph (device tree), coordinates enumeration, automatically starts drivers and allows communication between drivers of parent and child devices. DDF imposes certain structure of the driver and defines calls and entry points by which DDF and the driver communicate.

Internally DDF consists of a server, the Device Manager (devman) and the Device Driver Library (libdrv). Every driver is linked against libdrv, which internally communicates with the Device Manager via IPC — this is hidden from the driver. Device Manager holds information about drivers and device topology and coordinates operation of the drivers.

There is an administration tool associated with the Device Manager, devctl. devctl can be used to control operation of the Device Manager. It can display the device tree, offline and online devices (i.e. perform anticipated unplug operations).

DDF Driver Structure

When HelenOS runs the driver is an executable stored in /drv (e.g. /drv/foo). The driver is normally started automatically by the Device Manager. When the driver is needed, the Device Manager will start it and the driver connects to the Device Manager.

In HelenOS source tree drivers are located under uspace/drv. To add a new driver foo, you need to:

• create a directory uspace/drv/a/b/foo
• create a makefile uspace/drv/a/b/foo/Makefile
• create at least one source file uspace/drv/a/b/foo/foo.c
• add directory uspace/drv/a/b/foo to the DIRS definition in uspace/Makefile

You can use an existing driver as a starting point, for example uspace/drv/test/test1. A driver is a C program similar to a HelenOS server or application. It is linked with libdrv (and the makefile should add libdrv's include path to the header search paths). The most basic DDF interfaces are defined in the header ddf/driver.h.

• #include <ddf/driver.h>
• driver_t
• driver_ops_t
  • add_device (rename to dev_add)
  • dev_remove
  • dev_gone
  • fun_online
  • fun_offline
• ddf_dev_ops_t

Device and Function Life Cycle

• ddf_fun_create()
• ddf_fun_destroy()
• ddf_fun_add_match_id()
• ddf_fun_add_to_category()
• ddf_fun_bind()
• ddf_fun_unbind()
• ddf_fun_online()
• ddf_fun_offline()

Soft State Management

• ddf_dev_data_alloc()
• ddf_fun_data_alloc()

Exposing Driver Services to Clients

Traditional I/O Device Drivers

Programmed I/O

Interrupts

DMA

USB Device Drivers