ChorusOS 4.0 Device Driver Framework Guide

Driver Framework Components

Source Files

Typically, a driver component is a ChorusOS operating system supervisor actor written in 'C' programming language. This type of component (named devx for the example) is usually composed of the following files:

A header file (named devxProp.h) defining properties which are specific to this devx driver component. This file should be visible from the component(s) responsible for building the associated device tree node (to create the node's properties). This may be the boot program or any other "probe only" driver component.
An implementation file (devx.c) which contains the C code for the driver component. Note that for very big driver components, there may be multiple .c files. Note also that the hardware related definitions and constants are sometimes extracted from the .c file and put in a header file (devx.h) where use is restricted to the implementation file.
An Imakefile that is used to generate a Makefile (through the imake tool) in order to compile and link the driver component. Refer to the make and imake sections in "ChorusOS 4.0 Introduction", and the imake header file (see the TOOLS directory: installation_directory/platformtype-bin/dtool) for details about the imake macros that are available to build driver components.

Below is a typical example of an Imakefile, which exports a ravenProp.h file, compiles a raven.c implementation file and then builds a D_raven.r driver actor which is embedded in the archive.

CSRCS = raven.c

OBJS = $(CSRCS:.c=.o) 

BuiltinDriver(D_raven.r, $(OBJS), $(DRV_LIBS))

DistProgram(D_raven.r, $(DRV_DIST_BIN)$(REL_DIR))

Depend($(CSRCS))

FILES = ravenProp.h

DistFile($(FILES),)$(REL_DIR),$(DRV_DIST_INC)$(REL_DIR))

Organization (trees)

All files related to driver components are organized in 4 file trees:

The 'dki' tree, populated by the ChorusOS operating system delivery and exporting the DKI set of APIs (header files onl).
The 'ddi' tree, populated by the ChorusOS operating system delivery and exporting the DDI set of APIs (header files only).
The 'drv' tree, populated by generic driver components and exporting the device-specific properties header files. Generic driver components are drivers which do not use the family specific DKI APIs, and therefore are portable across all families and platforms (header and 'c' files).
The 'drv_f' tree, populated by processor family specific driver components and exporting device specific properties header files. Processor family-specific driver components are drivers which use one family specific DKI API, and therefore can run only on this processor family (header and 'c' files).

Note that both drv and drv_f trees are mainly populated by third party driver writers (although ChorusOS system deliveries contain drivers for the reference platform's devices).

The main functional components of the 'dki' tree are:

<dki/dki.h> which defines the Common DKI API
<dki/f_dki.h> which defines the processor family-specific DKI API

All other file trees are organized following the bus/device class provided APIs. In other words, there is a directory per class of bus and device, which contains the header file defining the API provided by this device class.

For drv and drv_f, in each bus/device class directory there is one directory per bus/device hardware controller for which a driver component is written.

Listed below are some path examples (header file paths are relative to the ChorusOS operating system delivery root directory):

    include/chorus/ddi/bus/bus.h              -> DDI's Common bus class API
    include/chorus/ddi/pci/pci.h               -> DDI's PCI bus class API
    include/chorus/ddi/uart/uart.h            -> DDI's UART device class API

    drv_f/src/pci/raven/ravenProp.h           -> family specific driver component
    drv_f/src/pci/raven/raven.h                      for the Motorola RAVEN PCI host
    drv_f/src/pci/raven/raven.c                       bridge
    drv_f/src/pci/raven/Imakefile

    drv/src/uart/ns16550/ns16550Prop.h    -> Generic driver component for
    drv/src/uart/ns16550/ns16550.h                NS16x50 compatible UART devices.
    drv/src/uart/ns16550/ns16550.c
    drv/src/uart/ns16550/Imakefile

Manpage Documentation

Typically, there is one manpage for each written driver component. The manpage file for a devx driver component is called 'devx.9drv' and accessible through the devx name. This manpage contains the following information:

the hardware that can be serviced by the driver
the driver name
the driver framework features and mechanisms that are implemented in the driver (probing, dynamic loading, and so on)
the description of device tree node properties used by the driver