Example

This section shows how to create a new BSP through an example. The example explains which files should be present in which directories in order to create the new BSP.

The Top Level BSP Directory

For this example, the new directory will be called MYBSP_SRC_DIR. This top level directory must contain the following four files:

---

Example A-5 New BSP: Makefile.bin

COMPONENT += BSP

BSP.all::

BSP_XML = target.xml target_action.xml

xml:: DEVTOOLS.all
        @sh $(DEVTOOLS_DIR)/cpxml $(BUILD_DIR)/conf/mkimage $(BSP) $(BSP_XML)

XML3 += mkimage/mkimage.xml

---

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

---

Caution -

Only the name BSP is required.

---

The xml target is used to copy the target.xml and target_action.xml file to the $(BUILD_DIR)/conf/mkimage directory. The mkimage/mkimage.xml is added to the XML macro. This XML file will be used at the end of the build to generate the image.

---

Example A-6 New BSP: Makefile.src

BSP_SRC = $(BSP)/src

all:: BSP.all 

BSP.all:: $(BSP_DIR)/DONE

$(BSP_DIR)/DONE: $(BSP_DIR)/Makefile 
        sh $(DEVTOOLS_DIR)/resync BSP -f $(BSP) -s $(BSP_DIR)
        cd $(BSP_DIR); $(MAKE)
        touch $(BSP_DIR)/DONE

$(BSP_DIR)/Makefile: $(BSP_SRC)/Imakefile
        sh $(DEVTOOLS_DIR)/ChorusOSMkMf $(BUILD_DIR) -s \
           $(BSP_SRC) -b $(BSP_DIR) -d $(BSP_DIR)
        cd $(BSP_DIR); $(MAKE) Makefiles

---

This makefile defines the BSP.all target used to compile and link the BSP source files.

The ChorusOSMkMf tool is used to create Makefiles from Imakefiles (see ChorusOSMkMf(1CC)for more details).

The BSP_DIR variable is defined as $BUILD_DIR)/build-BSP. This directory will be used as the build directory and the binary delivery directory.

---

Example A-7 New BSP: target.xml

<!DOCTYPE folder PUBLIC "-//Sun Microsystems//DTD ChorusOS//EN" "ChorusOS.dtd">

<fold      </description>
      <type name='Area' ref-only='yes' />
      <ref name='ram_area' />
    </definition>

    <definition name='user_context_area_ref'>
      <de      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='microkernel_model' /></value>
    </definition>
  </folder>

  <folder name='System image'>
    <description>ChorusOS system image configuration</description>

    <folder name='Files'>
      <description>system image files</description>

      <definition name='BSP_files'>
        <description>system image BSP files</description>

        <type name='FileList' />
        <value index='size'><ref name='debug_driver' /></value>
        <value index='size'><ref name='bootstrap' /></value>
        <value index='size'><ref name='microkernel' /></value>
      </definition>

      <folder name='Auto-generated files'>
        <description>
          system image files automatically generated by 'mkimage' tool
        </description>

        <definition name='bootconf'>
          <description>bootconf program</description>
          <type name='File' />
          <value field='path'>
            <vstring>${IMAGE_DIR}/bconf/${SYSTEM}_bconf.r</vstring>
          </value>
          <value field='bank'><ref name='sys_bank' /></value>
          <value field='binary'><ref name='bootconf_model' /></value>
        </definition>

        <definition name='symb'>
          <description>kernel debuger (kdb) symbols</description>
          <type name='File' />
          <value field='path'>
            <vstring>${IMAGE_DIR}/symb/${SYSTEM}_symb.r</vstring>
          </value>
          <value field='bank'><ref name='sys_bank' /></value>
          <value field='binary'><ref name='debug_agent_model' /></value>
        </definition>

        <definition name='env_file'>
          <description>
            initial state of system environment variables
          </description>
          <type name='File' />
          <value field='path'>
            <vstring>${IMAGE_DIR}/environ</vstring>
          </value>
          <value field='bank'><ref name='sys_bank' /></value>
        </definition>
      </folder>

    </folder>

    <folder name='Misc'>
      <description>Misc configuration variables</description>
        
      <definition name='banks'>
        <description>list of system image banks</description>
        <type name='BankList'/>
        <value index='size'><ref name='sys_bank' /></value>
      </definition>

      <definition name='heap_size'>
        <description>bootconf heap size</description>
        <int/>
        <const>0x00002000</const>
      </definition>

    </folder>

  </folder>

</folder>

---

The example target.xml file, above, specifies the basic routines needed to produce a kernonly archive. It is important to note that this file has to be adapted for your particular board.

The pathname ${BSP_DIR}/bin/mybsp is used to reference a number of BSP binaries. The mybsp name can be replaced by an explicit reference to your board. In this case, remember to change this path in the Project.tmpl file, detailed below.

---

Example A-8 New BSP: target_action.xml

<!DOCTYPE folder PUBLIC "-//Sun Microsystems//DTD ChorusOS//EN" "ChorusOS.dtd">

<folder name='MYBSP specific actions' visible='no'>
  <description>MYBSP system image action</description>

  <action name='Archive renaming'>
    <application>shellCommand</application>
    <definition name='shellCommand_cp'>
      <type name='ShellCommand' />
      <value field='command'>
        <vstring>cp</vstring>
      </value>
      <value field='argument'>
        <value index='size'>
          <vstring>${IMAGE_DIR}/bank/sys_bank</vstring>
        </value>
        <value index='size'>
          <vstring>${RESULT}</vstring>
        </value>
      </value>
    </definition>
  </action>

</folder>

---

The target_action.xml file, detailed above, copies the sys_bank file into a file defined by the RESULT variable. This variable is defined as ${BUILD_DIR}/${SYSTEM}, where ${SYSTEM} is the name of the image to be produced. Note that multiple banks can be combined, and specific binary format headers can be included, to produce a more complex system image.

The Src Level Directory

This src directory must contain the following two files:

---

Example A-9 New BSP: Project.tmpl

#include "Package.rules"

SRC_DIR         = SourceDir
BUILD_DIR       = BuildDir
DIST_DIR        = DistDir

VPATH           = $(SRC_DIR)$(REL_DIR)

WARN            = $(WARN_ON)

MYBSP_DIST_BIN  = $(DIST_DIR)/bin/mybsp

DRV_DIST_BIN    = $(DRV_DIR)/bin/drv

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

BSP_LIBS        = $(NUCLEUS_DIR)/lib/boot_tools/boot_tools.s.a \
                  $(NUCLEUS_DIR)/lib/util/util.s.a \
                  $(NUCLEUS_DIR)/lib/bki/bki.s.a \
                  $(NUCLEUS_DIR)/lib/cpu/cpu.s.a \
                  $(NUCLEUS_DIR)/lib/stdc/stdc.s.a \
                  $(NUCLEUS_DIR)/lib/boot_tools/sys/sys.s.a 

---

The MYBSP_DIST_BIN variable defines the directory to which programs will be exported. The name mybsp can be changed to the real board name. The DIST_DIR variable is defined by the path given with the -d option of ChorusOSMkMf. This path is the same as BSP_DIR: $BUILD_DIR/build-BSP. The DRV_DIST_BIN variable will be used to reference objects exported by the DRV component.

---

Example A-10 New BSP: Src-level Imakefile

#define IHaveSubdirs

SUBDIRS = boot dbg

---

This Imakefile lists all of the sub-directories for each BSP class and should not be edited.

The boot Directory

This is the directory where the source files for the boot program reside. There are at least two files in this directory:

---

Example A-11 New BSP: Imakefile

C__SRCS = boot.c

AS_SRCS =

OBJS = $(C__SRCS:.c=.o) $(AS_SRCS:.s=.o)
BspProgTarget(boot.r, start, $(OBJS), $(BSP_LIBS))

DistProgram(boot.r, $(MYBSP_DIST_BIN)$(REL_DIR))

Depend($(C__SRCS) $(AS_SRCS))

---

The BspProgTarget macro is used to produce the boot.r relocatable binary file. The final link will be done by the mkimage tool. The first argument is the name of the binary ( with the standard file extension .r for 'relocatable'). The second argument is the entry-point, the third is the list of objects and the fourth is the list of libraries used in the link process.

The DistProgram macro copies the file given by the first argument to the directory specified by the second argument. Therefore, in the example above, the boot.r binary file will be copied in to the $BSP_DIR/bin/mybsp/boot directory.

---

Example A-12 New BSP: boot.c

void
start()
{
    /* Code for your BSP boot */
}

---

This file needs to be adapted to cater for your BSP.

The dbg Directory

The dbg directory contains the platform dependant code for the debug agent driver. There are three files located at this top level:

---

Example A-13 New BSP: dbg Imakefile

C__SRCS = dbgBsp.c ns16550Bsp.c

AS_SRCS =

OBJS = $(C__SRCS:.c=.o) $(AS_SRCS:.s=.o)

DRIVERS = \
        $(DRV_DIST_BIN)/dbg/ns16550.o

BspProgTarget(dbgBsp.r, dbgBsp_init, $(OBJS), $(DRIVERS) $(BSP_LIBS))

DistProgram(dbgBsp.r, $(MYBSP_DIST_BIN)$(REL_DIR))

Depend($(C__SRCS) $(AS_SRCS))

---

Note that dbgBsp.r is linked with the ns16550.o object, which is located in the DRV component.

---

Example A-14 New BSP: dbgBsp.c

#include <bki/bki.h>
#include <bki/dbgBsp.h>

#include <drv/dbg/dbgUart.h>

extern void dbg_board_reset(int);

DbgBsp dbgBsp = { dbgUart_init,
                  dbgUart_ioctl,
                  dbgUart_mayGet,
                  dbgUart_getChar,
                  dbgUart_mayPut,
                  dbgUart_putChar,
                  dbgUart_ioRemap,
                  dbg_board_reset };

    void
dbg_board_reset(int mode)
{
    /* Code for your board reset */
}

    void
dbgBsp_init(BootConf* conf)
{
    conf->dbgBsp = dbgBsp;
}

---

Note that dbgBsp.c needs to be adapted for your board.

---

Example A-15 New BSP: ns16550Bsp.c

#include <drv/dbg/ns16550Bsp.h>

    void
ns16550_init(int port)
{
    /* Code for your board */
}

    void
ns16550_outb(unsigned int reg, unsigned char val)
{
    /* Code for your board */
}

    unsigned char
ns16550_inb(unsigned int reg)
{
    unsigned char c;
    /* Code for your board */
    return c;
}

    unsigned short
ns16550_divisor(unsigned int baud)
{
    unsigned short divisor;
    /* Code for your board */
    return divisor;
}

    void
ns16550_ioremap(void* newbase)
{
    /* Code for your board */
}

---

Note that the example above is for an ns16550 BSP. The file will be need to be adapted for your board.