ChorusOS 4.0 Porting Guide

Example

This section shows how a new driver can be created through the example of a non-existent keyboard chip 'zl345y'. The example explains which files should be present in which directories in order to create a new driver.

The Top' Level Driver Directory

For this example, the new directory will be called MYDRV_SRC_DIR. This root-level directory must contain the following two files:

Example A-1 New driver: `Makefile.bin`

COMPONENT += MYDRV

MYDRV.all::

The COMPONENT macro defines a list of components that will be processed in the build phase. The MYDRV source component is added to this list.

Example A-2 New driver: `Makefile.src`

MYDRV_SRC = $(MYDRV)/src

all:: MYDRV.all 

MYDRV.all:: $(MYDRV_DIR)/DONE

$(MYDRV_DIR)/DONE : $(MYDRV_DIR)/Makefile
        cd $(MYDRV_DIR); $(MAKE)
        touch $(MYDRV_DIR)/DONE

$(MYDRV_DIR)/Makefile: $(MYDRV_SRC)/Imakefile
        sh $(DEVTOOLS_DIR)/ChorusOSMkMf $(BUILD_DIR)
                         -s $(MYDRV_SRC) -b $(MYDRV_DIR) -d $(MYDRV_DIR)
        cd $(MYDRV_DIR); $(MAKE) Makefiles

This makefile defines the MYDRV.all target used to compile and link the MYDRV source files. The ChorusOSMkMf tool is used to create Makefiles from Imakefiles (see the ChorusOSMkMf(1CC) manpage for more details). The MYDRV_DIR variable is automatically set to $(BUILD_DIR)/build-MYDRV. This directory will be used as the build directory, for example where sources are compiled and linked. It will be used also as the binary delivery directory, for example where includes and binaries are exported.

Note -

These two files, Makefile.bin and Makefile.src , are referenced in the $BUILD_DIR/Makefile, which resides at the root of the build directory. The contents of both files should not be changed.

The Src Level Driver Directory

This src directory must contain the following two files:

Example A-3 New driver: `Project.tmpl`

#include "Package.rules"

SRC_DIR         = SourceDir
BUILD_DIR       = BuildDir
DIST_DIR        = DistDir

VPATH           = $(SRC_DIR)$(REL_DIR)

WARN            = $(WARN_ON)
DEBUG           = $(DEBUG_ON)

DRV_DIST_INC    = $(DIST_DIR)/include/chorus/drv

DRV_DIST_BIN    = $(DIST_DIR)/bin/drv

INCLUDES        = -I$(NUCLEUS_DIR)/include/chorus \
                  -I$(NUCLEUS_DIR)/include/stdc \
                  -I$(DIST_DIR)/include/chorus \
                  -I$(DIST_DIR)/include/chorus/drv/private \
                  -I$(SRC_DIR)$(REL_DIR)

CPU_LIB         = $(NUCLEUS_DIR)/lib/cpu/cpu.s.a
EBD_LIB         = $(NUCLEUS_DIR)/lib/embedded/libebd.s.a

DRV_LIBS        = $(CPU_LIB) $(EBD_LIB)

The DRV_DIST_INC and DRV_DIST_BIN variables define paths where includes and binaries will be exported. This Project.tmpl file can be modified to add new variables or modify existing ones, for example to add a new include path or add a new library (DRV_LIBS).

Example A-4 New driver: `Imakefile`

#define IHaveSubdirs

SUBDIRS = keybrd

This Imakefile lists all of the sub-directories for each driver class and needs updapting to cater for your own drivers.

The Driver Directory

In this example, for a keyboard driver, the driver class directory would be MYDRV_SRC_DIR/src/keybrd, along with all other keyboard drivers.

The keybrd.h include file defines the DDI interface of this new driver. This include file must be exported to a well-known place in order for it to be accessible to a client of this driver. For example:

#include <ddi/keybrd/keybrd.h>

For this reason, a DistFile macro appears in the Imakefile, as follows:

#define IHaveSubdirs  
SUBDIRS = zl345y  
DistFile(keybrd.h, $(DIST_DIR)/include/chorus/ddi/keybrd)

The Imakefile also contains a list of keyboard drivers for different chips.

The Chip Directory

The actual driver for the zl345y keyboard device would be located in MYDRV_SRC_DIR/src/keybrd/zl345y and consists of four files:

zl345y.c: the driver's code
zl345y.h: driver's definitions
zl345yProp.h: driver's properties
Imakefile

The Imakefile contains the following:

CSRCS = zl345y.c

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

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

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

Depend($(CSRCS))

DistFile(zl345yProp.h, $(DRV_DIST_INC)$(REL_DIR))

The BuiltinDriver macro is used to produce the D_zl345y.r relocatable binary. The final link will be done by the mkimage tool. The first argument is the name of the binary. r is the standard extension for relocatable files. The second argument is the list of objects and the third is the list of libraries used in the link process.

The DistProgram macro copies the file, given as its the first argument, to the directory specified by its second argument. In the above example, the D_zl345y.r binary will be copied to the $MYDRV_DIR/bin/drv/keybrd/zl345y directory.

The zl345yProp.h file is exported as code by the DistFile macro to allows other drivers to include it.

Adding the New Driver

Finally, the driver must be added to the ChorusOS operating system. This can be done by either:

Including the new driver in the ChorusOS operating system image, or
Dynamically adding the driver to the operating system

To include the new driver in the ChorusOS operating system image you will need to add the new driver's definition to the BSP target.xml file, as follows:

<definition name='zl345y'>
  <type name='File' />
  <value field='path'>
    <vstring>${MYDRV_DIR}/bin/drv/keybrd/zl345y/D_zl345y.r</vstring>
  </value>
  <value field='bank'><ref name='sys_bank' /></value>
  <value field='binary'><ref name='driver_model' /></value>
</definition>

Also, a reference to the new driver will need be to be made in the BSP FileList:

<definition name='BSP_files'>
  <description>system image BSP files</description>
  <type name='FileList' />
   ....
  <value index='size'><ref name='zl345y' /></value>
   ....
</definition>

Alternatively, to add the driver dynamically, after the system image has been created, the arun command should be used to run the new driver.