Appendix B Porting the Debug Agent

This appendix explains how to port the debug agent to a new board.

Source Files

There are two binary files in the ChorusOS operating system bootable image that you must consider when porting the debug agent:

• dbgAgent contains generic and processor specific debug agent code. It is platform independent.

• dbgBsp contains serial line device driver and board reset functions.

The interface between dbgAgent and dbgBsp is described in include/chorus/bki/dbgBsp.h.

dbgAgent

The debug agent source code can be found in the common/src/dbg and family/src/dbg directory trees. As this code is platform independent, you should not need to modify it.

dbgBsp

The source code for generic serial device drivers can be found in the drv/src/dbg subtree. There are two files per driver: Bsp.h and a file defining the interface to platform specific functions. This interface is device driver dependent.

The dbgBsp platform-specific source code can be found in the /src/dbg directory tree.

A serial line device driver is platform independent. It depends only on a chip used for serial I/O. A serial line device driver calls a small number of platform dependent functions in order to access device registers. If a generic driver already exists for your platform, you only need to modify these functions. If no generic device driver exists for a chip on your platform, create one using the generic serial line device driver interface described in drv/src/dbg/dbgUart.h.

Example

This section describes a dbgBsp for the PowerPC Genesis-2 board. The source files for this example are in powerpc/genesis2/src/dbg. There are three files in this directory:

• dbgBsp.c

• ns16550Bsp.c

• Imakefile

dbgBsp.c:

• Declares and initializes a dbgBsp structure (as defined in bki/dbgBsp.h)

• Implements the board reset function

• Calls the serial driver initialization function and initializes the dbgBsp field in the BootConf structure

• Contains dbgBsp_init, which is an entry point for dbgBsp

ns16550Bsp.c:

• The ns16550_inb(), ns16550_outb() functions provide access to device registers.

• The ns16550_divisor() function calculates the divisor corresponding to a given baud rate, which is then used to program the baud rate in the generic driver.

• The ns16550_ioremap() function is called each time the I/O space mapping is changed.

Imakefile:

• Builds dbgBsp binary file from dbgBsp.o and ns16550.o

• Includes $(DRV_DIST_BIN)/dbg/ns16550.o (the generic driver) and $(DRV_DIST_BIN)/dbg/dbgUartConf.o (the serial line configuration) in the binary file

• Declares dbgBsp_init as the entry point