ChorusOS 5.0 Board Support Package Developer's Guide

Chapter 2 Overview of Porting and Creating new Drivers

This chapter contains an overview of the BSP source files in the installed directory structure. It also describes the main tasks involved in porting ChorusOS to a new board in a supported family, and when adding a new device driver.

ChorusOS BSP Source Tree

This section describes the BSP source tree that is contained in a ChorusOS binary product. These files are contained in the source_dir/nucleus/bsp directory. Figure 2-1 shows all the target family directories. However, when you install ChorusOS for a particular target family only one family/ directory will be in the source tree : the one that corresponds to the target family that you have installed.

Figure 2-1 BSP Source Tree Showing all Target Families

There is a part of the BSP that is specific to the target board. This is contained in the board directories that you will find under the associated family directory. For example, for a reference board, the SBC8260, the sbc8260/ directory that is contained in the powerpc/ directory.

When configuring and building ChorusOS for a reference board the source_dir/nucleus/bsp/family/board/ directory corresponds to the BSP component (see configure(1CC)).

The other part of the BSP consists of generic and target family specific drivers. These files that are contained in source_dir/nucleus/bsp/src/ directory. The generic drivers are contained at the root of this directory, grouped by DDI, and the specific drivers are contained in the directories under the family/ directory.

The source_dir/nucleus/bsp/ directory corresponds to the DRV component that you need to specify when configuring your ChorusOS build directory using the configure command. The processor family specific drivers are automatically selected for your board, depending on the target family. When adding a new driver to a ChorusOS system image, you may also add a new MYDRV component. In this situation the source for your driver may be in any other location. For more information see Chapter 10, Writing a New Device Driver.

Overview of Creating a Board Support Package

This section contains a general overview of one of the ways of porting ChorusOS to a new target board within a reference target family. Each of the main steps refers to the part of the document that contains more detail on carrying out this step.

Creating a new Board Support Package

Create a new BSP subtree (within the ChorusOS BSP source tree or in another location).

Duplicate the files from the supported BSP that most resembles your new target: create source_dir/nucleus/bsp/family/my_board/* (see Chapter 3, Writing a New Board Support Package).

Adapt the boot program for your target system.

In most cases the boot.c program for the particular target family can be reused, as is, for your new board (see Chapter 4, The ChorusOS Boot Program).

Adapt the reboot program for your target system.

In most cases the reboot.c program for the particular target family can be reused, as is, for your new board (see Chapter 5, The ChorusOS Reboot Program).

Adapt the BSP part of the debug agent for your target system.

Typically this is the debug agent console driver, watchdog driver and board reset services: dbgBsp.c, uart.c and wdt.c files (see Chapter 6, Porting the Debug Agent and Hot Swap Support for more information on the dbgAgent).

Adapt/write the power-up initialization code for the target board.

Note that this step may be omitted or done later, if your target board has firmware which enables the ChorusOS operating system to be downloaded (see "Power-up Program Implementation").

Adapt/create the ChorusOS operating system configuration files that are specific to the target board:

target.xml and target_action.xml (see Chapter 7, Configuring the ChorusOS System Image).

Write the code for the device drivers, if any additional ones are required.

Note that as a minimum a timer driver is required for the system tick. The host bus bridge driver must also be available if the tick timer device is external to the processor. For more information on writing a device driver see Chapter 10, Writing a New Device Driver. For more information on writing a host bus driver see Chapter 11, Writing a New Bus Driver.

Configure, build and test the ChorusOS system image, using the tools provided in the Sun Embedded Workshop: cdstool, configure, make or ews (see "Building and Build Tools" in ChorusOS 5.0 Source Delivery Guide).

Note -

A new BSP may be tested in two phases. You may initially want to build a system image that contains just the boot programs and a minimal set of drivers (for example, the tick timer). Once the first phase is successful, you can build a more complete system image that contains other required bus/device drivers. These can be added and tested one at a time.

Overview of Creating a New Device/Bus Driver

This section contains a general overview of how to create a new device driver. A device driver is represented by a static variable that contains information on where the driver can be found, and what devices it supports, as well as its standard entry points for the driver framework. For more information on what is involved in the following steps see Chapter 10, Writing a New Device Driver and Chapter 11, Writing a New Bus Driver.

Creating a new Device/Bus Driver

Create a new driver root directory within the ChorusOS DRV (source_dir/nucleus/bsp/src) component source tree (or in another location).

Depending on whether the driver is generic or specific to a particular target family, you organize the new driver directory in the ddi/ or family/ddi directories.

Create a driver actor whose main routine registers your device driver structure in the driver registry.

This is implemented in the files my_drv.c and my_drvProp.h (for any constant values). For more information see "Driver Registry".

Modify the Imakefile of the parent directory to include the new my_drv directory, and create a new Imakefile within the directory.

For example:

CSRCS = my_drv.c
OBJS = $(CSRCS:.c=.o)
BuiltinDriver(D_my_drv, $(OBJS), $(DRV_LIBS))
DistProgram(D_my_drv, $(DRV_DIST_BIN)$(REL_DIR))
Depend($(CSRCS))

Modify the target.xml file of the board that you are adding driver support for.

You need to add the definition and path of your driver to the Files folder, and the driver name to the file list in the System image folder. For some platforms the target.xml file is split into multiple files: drivers.xml, drvlist.xml, target.xml. In this situation you will find the File folder in the drivers.xml file, and the drivers to be included in the system image would be included in the drvlist.xml file.

For example you would need to add the following sections to specify your new driver:

<folder name='Files' configurable='yes'>
  <description> files...</description>
  ...
  <definition name='my_drv'>
    <type name='File' />
    <value field='path'>
      <vstring>${DRV_DIR}/bin/drv/<ddi>/my_drv/D_my_drv</vstring>
    </value>
    <value field='bank'><ref name='sys_bank' /></value>
    <value field='binary'><ref name='driver_model' /></value>
  </definition>
...
<folder name='System image'> 
  ...
  <folder name='Files'>
    <description>system image files<description</description>
      <definition name='BSP files' configurable='yes'>
        <description>system image BSP file</description>
         <type name='File list' />
         ...
         <value index='size' ><ref name='my_drv' /></value>
         ...
      </definition>
  ...

You may need to add a new device node to the ChorusOS device tree, that represents the new physical device.

To do this you will need to modify the deviceTree.c file. Creating the device node statically in this way is only required if there is no automatic processing policy for this kind of device. Typically a PCI device may be dynamically discovered at runtime. It may also be required if specific configuration properties have to be attached to that device node (for example, properties that cannot be created by dynamic probing).

Write the implementation of the standard driver routines that are exposed as entry points to the Driver Framework in the driver registry.

These are drv_probe(), drv_init(), drv_bind(), drv_unload() in the driver source files.

Build and boot the new ChorusOS system image with the new driver embedded in it.

Your new driver is registered in the driver registry. Alternatively, you can build the driver and manually start it on an already running ChorusOS system.

Assuming that the physical device is present on the target board, the driver entry points should be called by the framework and a driver instance started for the device.