Driver Framework Components

This section describes the elements of the Device Driver Framework in the ChorusOS operating system.

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 Application Developer's Guide", and the imake header file. See the TOOLS directory: install_dir/chorus-family/tools/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 driver actor which is embedded in the system image.

Example 8-1 Imakefile to Build the D_raven Driver Actor

CSRCS = raven.c

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

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

DistProgram(D_raven, $(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 three file trees:

• The 'dki' tree, populated by the ChorusOS operating system delivery and exporting the DKI set of APIs (header files only).

• 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 as well as processor family specific driver components. Each exports 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). 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 the drv tree is 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 the generic drivers are classified by DDI and are contained in corresponding directories, whereas the family-specific drivers are contained in family directories.

Listed below are some path examples (header file paths are relative to the ChorusOS operating system delivery source_dir 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

nucleus/bsp/src/powerpc/pci/raven/ravenProp.h, nucleus/bsp/src/powerpc/pci/raven/raven.h, nucleus/bsp/src/powerpc/pci/raven/raven.c, nucleus/bsp/src/powerpc/pci/raven/Imakefile

family specific driver component for the Motorola RAVEN PCI host bridge

nucleus/bsp/src/uart/ns16550/ns16550Prop.h, nucleus/bsp/src/uart/ns16550/ns16550.h, nucleus/bsp/src/uart/ns16550/ns16550.c, nucleus/bsp/src/uart/ns16550/Imakefile

Generic driver component for NS16x50 compatible UART devices

Driver Documentation

Typically, there is one man page for each driver component that is supplied with the ChorusOS operating system. The man page file for a devx driver component is called devx.9drv and accessible through the devx name. This page 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