The Tar Pit

Since I did mention these recently, I might as well lay out in blog form whatever notes I have gathered so far, for future reference. Comments are more than welcome, of course, although as mentioned in previous instances, I doubt that this will be useful to anybody but myself and the proverbial alien anthropologist.

For the sake of both exercise and rigorousness, let us take some space to define the item under examination: a device driver is a piece of software, usually (but not necessarily!) delivered as part of an operating system, providing automation in order to mediate interaction between a user and a so-called "device". Said device may be a logical entity, such as a database, say, a FAT32 partition¹, or otherwise a physical object such as a peripheral, say, a communication bus or a disk. These examples were not chosen arbitrarily, rather we use them to illustrate that drivers interact with one another: the system requires a communication bus to interact with the disk²; and it requires the disk in order to provide persistent storage for the database. And furthermore, the system requires some sort of user-facing application to expose the database to the human user -- but let us not be fooled, the driver, although supposedly a mechanism, is in fact an application for its user, i.e. the aforementioned user-facing application.

To sum this up: a driver is just another fancy name for an application that drives some underlying mechanism. When applied to Unix systems, the architectural specifics of these "driver applications" only serve to (irritatingly) drive us down a rabbit hole. While a few select Unix flavours³ treat all applications the same, most Unix systems enforce a more or less arbitrary divide between a so-called "kernel space" and "user space". The latter among the two (supposedly) runs user applications, while the former runs drivers, although in all fairness, the arbitrariness of this divide leads to situations where device drivers such as filesystems or GPU drivers end up running in user space⁴ and, why not, vice-versa, although no examples come to mind.

While in the Linux source tree, device drivers reside in the "drivers" directory, in OpenBSD they may be found in sys/dev⁵. Confusingly enough, however, basic definitions pertaining to device drivers do not reside there: since (some) drivers may also be accessed directly by user space applications⁶, and the user-kernel interface is hosted by sys/sys (which consists entirely of header files), device driver definitions are placed in sys/sys/device.h. A quick glance reveals this classification:

/*
 * Minimal device structures.
 * Note that all ``system'' device types are listed here.
 */
enum devclass {
    DV_DULL,        /* generic, no special info */
    DV_CPU,         /* CPU (carries resource utilization) */
    DV_DISK,        /* disk drive (label, etc) */
    DV_IFNET,       /* network interface */
    DV_TAPE,        /* tape device */
    DV_TTY          /* serial line interface (???) */
};

So by and large OpenBSD supports the following types of devices: generic⁷, CPU⁸, disk, networking, tape⁹ and serial/console. Devices are modelled through the following data structure:

struct device {
    enum    devclass    dv_class;     /* this device's classification */
    TAILQ_ENTRY(device) dv_list;      /* entry on list of all devices */
    struct  cfdata     *dv_cfdata;    /* config data that found us */
    int                 dv_unit;      /* device unit number */
    char                dv_xname[16]; /* external name (name + unit) */
    struct  device     *dv_parent;    /* pointer to parent device */
    int                 dv_flags;     /* misc. flags; see below */
    int                 dv_ref;       /* ref count */
};

The less obvious fields there are: cfdata, parent and flags. There is indeed only one (generic) flag, DVF_ACTIVE, which signals device activation. The parent field on the other hand immediately brings to mind the hierarchical object-oriented model, so devices don't lie in a flat world etc. Finally, cfdata is a record of its own:

/*
 * Configuration data (i.e., data placed in ioconf.c).
 */
struct cfdata {
    const struct    cfattach *cf_attach;    /* config attachment */
    struct  cfdriver         *cf_driver;    /* config driver */
    short                     cf_unit;      /* unit number */
    short                     cf_fstate;    /* finding state (below) */
    long                     *cf_loc;       /* locators (machine dependent) */
    int                       cf_flags;     /* flags from config */
    short                    *cf_parents;   /* potential parents */
    int                       cf_locnames;  /* start of names */
    short                     cf_starunit1; /* 1st usable unit number by STAR */
};

I'm not sure how to describe the whole thing in a single (plain English) sentence, but let's try: any OpenBSD device has a configuration that combines a bunch of elements, the foremost among them being a so-called "config attachment" and a "config driver". In short, the former specifies under which condition a driver may be "attached" to its underlying device (i.e. when it's placed into operation); while the latter specifies information about the device instances that are driven. In more detail:

struct cfattach {
    size_t     ca_devsize;      /* size of dev data (for malloc) */
    cfmatch_t  ca_match;        /* returns a match level */
    void     (*ca_attach)(struct device *, struct device *, void *);
    int      (*ca_detach)(struct device *, int);
    int      (*ca_activate)(struct device *, int);
};

struct cfdriver {
    void    **cd_devs;          /* devices found */
    char    *cd_name;           /* device name */
    enum    devclass cd_class;  /* device classification */
    int     cd_mode;            /* device type subclassification */
    int     cd_ndevs;           /* size of cd_devs array */
};

At this point I'm not sure how one would go about writing a driver based on this information alone. In addition to this, writing a Unix -- or, in particular, a BSD, or, in particular, an OpenBSD -- driver requires access to priors which are only available to the OS designer. In other words, if one isn't privileged enough to have been there when the original Unix was created, or otherwise to have learned from one of those folks, one is advised to (re)view the synthetic materials provided by Tanenbaum and Silberschatz. Intuitively, we may state that: on one hand, the user¹⁰ has some degree of control over what applications he or she wishes to load in their system, be they of the "userland" or the "kernelland" variety; while from the other perspective, not all hardwares are created equal, and inasmuch as the kernel can "decide" things, it must be able to load or otherwise to refuse loading a driver when faced with this decision.

I guess that at this point the best way to go about this is by means of example. I have arbitrarily selected the generic General-Purpose Input/Output (GPIO) driver in sys/dev/gpio/gpio.c for this purpose:

struct gpio_softc {
    struct device sc_dev;

    gpio_chipset_tag_t       sc_gc;     /* GPIO controller */
    gpio_pin_t              *sc_pins;   /* pins array */
    int                      sc_npins;  /* number of pins */

    int sc_opened;
    LIST_HEAD(, gpio_dev)    sc_devs;   /* devices */
    LIST_HEAD(, gpio_name)   sc_names;  /* named pins */
};

int gpio_match(struct device *, void *, void *);
int gpio_submatch(struct device *, void *, void *);
void    gpio_attach(struct device *, struct device *, void *);
int gpio_detach(struct device *, int);
int gpio_search(struct device *, void *, void *);
int gpio_print(void *, const char *);
int gpio_pinbyname(struct gpio_softc *, char *gp_name);
int gpio_ioctl(struct gpio_softc *, u_long, caddr_t, int);

const struct cfattach gpio_ca = {
    sizeof (struct gpio_softc),
    gpio_match,
    gpio_attach,
    gpio_detach
};

struct cfdriver gpio_cd = {
    NULL, "gpio", DV_DULL
};

I shall be brief regarding GPIO: some machines¹¹ expose a set of programmable pins that the user may employ for whatever purpose he wishes, but in general in order to control some peripheral piece of equipment such as an audio processor or a robotic arm. While there is no specific standard defining this "GPIO" thing, they all pretty much work the same, in that they eat or produce a logic level or a digital signal or in any case, some data or the other. The hardware-specific implementation details are covered in separate device drivers¹² which sit below this "generic" driver.

A few observations on the generic GPIO driver.

First, the gpio_softc structure encompasses sc_dev. This is yet again reminiscent of object-orientation, in that the GPIO device is a subclass and a superset of the generic device. This idiom, or design pattern if you will, is not accidental.

Second, and furthermore, the gpio_{match,attach,detach} functions all receive as argument a device structure, which puts them in their place as methods in this object-oriented model -- in particular, in gpio_attach (or in any other "attach" method) the first device structure is the parent, while the second one is the "self", i.e. an equivalent of the C++ "this" keyword. At this point the reader is encouraged to look further into the definitions of these methods.

Third, the aforementioned methods are encapsulated in a cfattach object. Intuitively, when a driver is loaded, "match" is first called, and if it "succeeds" (whatever that means), then "attach" loads the driver, and subsequently "detach" unloads the very same. These methods are called in different places throughout the kernel code -- the core is in sys/kern/subr_autoconf.c if you're curious -- I won't go into details.

Fourth and finally, a cfdriver object is defined, which comes with some, but not many pre-populated fields. In particular the author provides cd_name and cd_class -- in this particular case, "gpio" and DV_DULL, that is, the class denoting a generic driver.

Other than the intuition that "attach" is a sort of "module init" and "detach" is a sort of "module exit", I'll skip any parallels with Linux. Long story short, these are the basic elements required to add a driver in OpenBSD. It isn't as gruesome as some may think, so who knows, I may go a tad deeper in the future.

Filed under: computing.
RSS 2.0 feed. Comment. Send trackback.