ChorusOS 5.0 Board Support Package Developer's Guide

Chapter 6 Porting the Debug Agent and Hot Swap Support

This chapter describes the architecture of the ChorusOS debug agent with details on how to adapt it to run on your new board.

"The Debug Agent" describes the ChorusOS debug agent.
"dbgAgent" describes the dbgAgent binary file and considerations when porting to a new target board.
"dbgBsp" describes the dbgBsp binary file and considerations when porting to a new target board.
"BSP Hot Swap Support" describes the BSP hot swap support and considerations when porting to a new target board.

For more information about debugging your ported system using debug agent, see "Debugging ChorusOS Systems" in ChorusOS 5.0 Debugging Guide.

The Debug Agent

The debug agent provides debug services as soon as ChorusOS has succesfully booted, enabling you to debug your ported ChorusOS system. Figure 1-1 shows the component architecture of ChorusOS and the parts of the BSP that must be adapted to your target architecture. The debug agent is not board specific but it relies on some debug critical drivers that are board specific. Therefore some work must be done to ensure that the debug agent works on your new board.

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, board reset functions, and other debug critical drivers.

The interface between dbgAgent and dbgBsp is described in source_dir/nucleus/sys/common/src/kern/bki/dbgBsp.h.

`dbgAgent`

The debug agent source code can be found in the source_dir/nucleus/sys/common/src/dbg and source_dir/nucleus/sys/family/src/dbg directory trees. As this code is platform independent, you should not need to modify it and in fact you only have access to this code if you have a source delivery of the ChorusOS operating system.

`dbgBsp`

The dbgBsp consists of two main parts (see Figure 6-1) that interface with some critical devices that enable boot and debugging facilities. The first part is a device independent (but driver dependent) interface adaptation layer that links the debug agent and the debug criticial devices.

Figure 6-1 Debug Agent Showing Debug Critical Drivers

The second part is made up of the device drivers that are used to manage the chips that the dbgBsp requires to be able to provide its services. This part is device (chip) dependent and implements the device independent interfaces that are defined in the upper layer.

For all boards that the ChorusOS operating system is supported on, the devices that must be implemented are the same: UART and WDT. However, the chips required by these devices are different.

The device-dependent (but chip-independent) definition files can be found in the source_dir/nucleus/bsp/src/dbg directory. There is a header file per device that defines the interfaces: dbgWdt.h and dbgUart.h.

The instanciation of this interface (or the stubs) can be found in the same directory. The naming convention for these files is: device.c and deviceBsp.h. The header file defines the functions from the device driver that can be used to implement the dbgBsp services. The C source file implements these services using the device driver calls that are defined in the header file. For example epfpld.c is a simple dbgBsp service that uses the epfpld device driver.

The Imakefile of this directory only lists the object files for independent compilation, and the headers that will be exported.

The second part of the dbgBsp is platform dependent. In this part the dbgBsp is first described in the Imakefile in terms of "what device drivers are used for this platform". This is where is it stated that for the SPARC CP1500, the dbgBsp relies on ns16550 UART driver and an epfpld WDT driver. This Imakefile can be found in the source_dir/nucleus/bsp/family/my_board/src/dbg directory. In this directory, you will also find the source for the implementation of the device driver interface defined in the deviceBsp.h file.

When porting to a new board you will need to write both the serial device drivers and the WDT device driver.

Example

This section describes a dbgBsp for the UltraSPARC CP1500 board. The source files for this example are in the source_dir/nucleus/bsp/usparc/cpxxxx/src/dbg directory. There are three files in this directory:

dbgBsp.c
ns16550Bsp.c
epfpldBsp.c
Imakefile

dbgBsp.c:

Declares and initializes a dbgBsp structure (as defined in bki/dbgBsp.h)
Implements the board reset function
Calls the serial and watchdog driver initialization functions 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

epfpldBsp.c:

The epfpld_init() function assigns an initial physical address to the watchdog device
The epfpld_pat() function resets the watchdog counter if the system is stopped by the system debugger
The epfpld_ioremap() function assigns a new physical address to the watchdog device

Imakefile:

Builds the dbgBsp binary file from dbgBsp.o, ns16550.o and epfpld.o
Includes $(DRV_DIST_BIN)/dbg/ns16550.o, $(DRV_DIST_BIN)/dbg/dbg/epfpld.o (the generic drivers) and $(DRV_DIST_BIN)/dbg/dbgUartConf.o (the serial line configuration) in the binary file
Declares dbgBsp_init as the entry point

BSP Hot Swap Support

The Compact PCI bus is an extension of the PCI bus which enables a board to be inserted or removed when the bus is powered up. The ENUM# signal is a specific bus signal which notifies of such an event. The support of hot swap in the BSP consists of the following:

stopping a device driver instance when a board is extracted
starting a new device driver when a board is inserted

The implementation of the BSP hot swap support in the ChorusOS operating system is across three levels of drivers:

Hot Swap Controller
pciswap generic driver
PCI bridge PciswapEvent handlers

The Hot Swap Controller is responsible for receiving and handling the ENUM# signal and providing a generic interface to manage the corresponding event/interrupt. Usually this driver is board specific.

The pciswap driver is generic and provides an interface for forwarding the PciSwap events to its client. Its role is to probe the PCI configuration space and to read the HS_CSR register (defined by the PICMG Hot Swap specification). Therefore, it detects which device has been inserted or is going to be removed, and notifies its client.

The PciswapEvents handlers are implemented in the CompactPCI bridge device driver. This driver is the client of the pciswap driver and uses its interface to manage the PciSwap events. The handler of the corresponding events are responsible for starting or stopping the child drivers.

Reference Implementation

This section contains a list of the reference boards for hot swap support and the corresponding drivers used in the implementation. More information on these can be found the corresponding man page in the 9DRV section:

CP1500

usparchsc(9DRV): Hot Swap Controller
pciswap(9DRV): PciSwap driver
dec2115x(9DRV): PciSwap client

MCP750

gpiohsc(9DRV): Hot Swap Controller
pciswap(9DRV): PciSwap driver
dec2115x(9DRV): PciSwap client

CPN5360

fpga(9DRV): Hot Swap Controller
pciswap(9DRV): PciSwap driver
dec2155x(9DRV): PciSwap client

Porting Hot Swap

The pciswap driver is generic and may be used on any board. It provides a drv_probe() routine so there is no need to add a node in the device tree for this driver.

The following sections give more information on the drivers that may need to be written when porting to a new board.

Hot Swap Controller

In the ChorusOS operating system the following Hot Swap Controller drivers are provided (one reference board per target family):

As the Hot Swap Controller is supposed to attach a handler to the ENUM# interrupt, this driver is very board specific.

PCI Bridge PciSwapEvents Handlers

The following are implemented as PciSwap clients: dec2115x(9DRV), dec2155x(9DRV). If the compact PCI bridge of the new board is not one of these, the PciswapEvents handlers need to be implemented.

The Device Tree

A node for the Hot Swap Controller must be added in the device tree. The HSC_PROP_BUS_PATH property and its corresponding value must be added to this node. This property describes the bus from which the devices may be hot swapped.