ChorusOS 5.0 Transition Guide

Part IV Transition Information for BSP Developers

The ChorusOS source trees have been reorganized in version 5.0 to be more efficient. This part of the guide provides an overview of this reorganization and includes a description of changes to the device driver framework, the DDIs and DKIs, and the boot libraries and boards.

Chapter 10 Changes to DDIs and DKI Extensions

This chapter lists the changes made to the Device Driver Interfaces and the Driver Kernel Interface extensions.

Changes to DDIs

This section describes the DDIs that have been changed or updated in version 5.0 of the ChorusOS operating system, as well as the new DDIs that have been added.

Updated DDIs

The following DDIs have been changed:

Common Bus DDI

An extended version of the Common Bus DDI is defined (BUS_VERSION_1). Most of the extensions relate to the device driver hardening framework.

PCI Bus DDI

An extended version of the PCI Bus DDI is defined (PCI_VERSION_1). Most of the extensions are related to the device driver hardening framework.

NVRAM DDI

The main modifications to this DDI have been made in the device properties.

The NVRAM layout configuration has changed as follows:

It is now described by the node property NVRAM_PROP_LAYOUT. The data associated with this property is an array of NvramPropChunk.
Each chunk in NVRAM now has a specific ID (1..254).

There are also two special IDs, NVRAM_KERNEL and NVRAM_RESERVED. NVRAM_KERNEL describes a section reserved for microkernel data, such as boot information. The NVRAM_RESERVED sections should never be written to or read but can be used to protect sections used by firmware.

In addition, the M48txx driver has been enhanced to include the new property M48TXX_PROP_REG_OFF. This property is used to define device register offset dynamically. The enhancement to the M48txx driver includes support for the m48t37v chip.

Flash DDI

The Flash DDI has been redesigned to include generic drivers. (Certain parts of old drivers are board-specific).

While there is no change to the existing Flash DDI, the redesign provides the new Flash Control DDI (see "Flash Control DDI") which allows communication between generic and specific drivers.

Ethernet DDI

Version 5.0 of the ChorusOS operating system provides an extended version of the Ethernet Device DDI (ETHER_VERSION_1 ). The extended DDI enables the driver to avoid making an extra copy of the frame buffer to or from the device DMA buffer. It is therefore possible to send and receive ethernet frames directly to and from the client buffers.

The extended DDI also supports TCP/UDP hardware checksum on reception and transmission.

New DDIs

The following new DDIs have been added:

Flash Control DDI

The flash control DDI provides a basic interface by abstracting board-specific operations for flash device write enabling and disabling management. The driver implements routines that allow the device driver client to enable and disable the write access on a flash device.

For more information on the Flash Control DDI, refer to "Driver Framework APIs" in the ChorusOS 5.0 BSP Developer's Guide and to the flashCtl(9DDI) man page.

Watchdog Timer DDI

The new watchdog timer is essentially a counter driven by a clock signal. The watchdog timer DDI provides a countdown register, which is the main timer. This register is decremented at each clock tick. Its initial value is set through the limit register, either at initialization time, or at pat time.

If the countdown register reaches zero, a signal is alerted to produce a specified effect (hard reset, soft reset or interrupt). Depending on the type of watchdog device, it is possible to "pat" the timer to avoid this effect. This "patting" of the timer must occur at regular intervals.

The watchdog timer device may operate in two separate modes:

reset mode
interrupt mode

When operating in the reset mode, the watchdog device asserts a board reset signal if a watchdog timeout occurs. When operating in interrupt mode, the watchdog device asserts an interrupt line if a watchdog timeout occurs. The watchdog timer driver interface allows the watchdog device to operate in any mode.

For more information on how the watchdog timer is implemented in ChorusOS 5.0, refer to "Analyzing System Failure: Black Boxes, Watchdog Timers and Logging" in the ChorusOS 5.0 Application Developer's Guide and to the wdtimer(9DDI) man page.

IDE/ATA DDI

A new architecture has been implemented to provide support for IDE disks and CompactFlash devices. The new architecture includes new Disk and ATA DDIs.

The new Disk DDI is a general purpose DDI, supporting all disks. The ATA DDI provides an API for the employment of ATA device drivers. For more information, see the ata(9DDI) and disk(9DDI) man pages.

Bus Communication DDIs

To provide communication protocols over an I/O bus, the ChorusOS operating system implements a layered architecture composed of the following:

A physical (low) layer which includes the bus control DDI, the local bus communication DDI and the remote bus communication DDI.
A logical (middle) layer which includes the bus multiplexor DDI.
A protocol (high) layer which includes the ethernet driver (using the multiplexor DDI) and the TCP/IP stack.

The physical layer abstracts the bus architecture, enabling the portability of all upper layers. The main task of the physical communication driver is to make shared memory resources accessible from any board within the communication domain.

Typically, among all physical drivers running on a given CPU board, there is one driver that provides access to the board local memory (exported to the bus). All other physical drivers provide access to the remote memory (imported from the bus). Thus, the total number of physical drivers on a CPU board (visible for the multiplexer) is always equal to the number of CPU boards communicating over the bus (or buses). Another task of the physical layer is to provide interrupt services allowing a cross interrupt to be sent from one CPU board to another.

The logical communication driver (multiplexer) uses services provided by the physical drivers (shared memory and cross interrupts) to implement a low-level communication protocol over the bus. While various implementations of such a communication layer are possible, the ChorusOS operating system implements a basic communication protocol providing simplex (unidirectional) communication channels over the bus.

For more information on these DDI's refer to the buscom(9DDI) and busmux(9DDI) man pages.

PCI Resource Manager DDI

The new PCI Resource Manager DDI is used internally by PCI bus drivers to manage PCI bus resources dynamically. This avoids code duplication in all PCI bus drivers as they can rely on a single, generic PCI resource manager driver for the dynamic resource allocation services defined by the PCI DDI. For more information, see the pcimngr(9DDI) man page.

Keyboard DDI

The keyboard DDI (asynchronous mode) defines the upper interface for keyboard device drivers. For more information, see the keyboard(9DDI) man page.

Mouse DDI

The mouse DDI defines the upper interface for mouse device drivers. For more information, see the mouse(9DDI) man page.

PCMCIA Bus DDI

The PCMCIA bus driver provides an API for PCMCIA development. This PCMCIA bus API is an abstraction of the low-level PCMCIA bus services and covers the following PCMCIA functional modules

PCMCIA interrupt management
Access to the I/O device registers
Access to the memory of the PCMCIA device
Power management of the PCMCIA device
Generation of PCMCIA device events

For more information, refer to the pcmcia(9DDI) man page.

GPIO DDI

The General Purpose I/O (GPIO) DDI provides an interface for device driver development. This DDI abstracts operations for a general purpose I/O port device. For more information, refer to the gpio(9DDI) man page.

Hot Swap Controller (HSC) DDI

This DDI provides a generic interface for handling the ENUM# signal on system CompactPCI boards. For more information, see the hsc(9DDI) man page.

PCI Swap DDI

The PCI Swap DDI provides a generic interface to access the Hot Swap control and status register. For more information, refer to the pciswap(9DDI) man page.

Media Independent Interface (MII) DDI

The MII DDI provides MII bus driver interface services. The MII bus is a generic bus that connects different types of network physical transceivers (PHYs) to the same network controller. For more information, see the mii(9DDI) man page.

Transceiver (PHY) DDI

The ethernet PHY transceiver DDI provides PHY device driver services. For more information, see the phy(9DDI) man page.

Management DDI

The management DDI provides services allowing a client to manage device and driver pairs as components. This interface is the same for all classes of bus and device drivers. For more information, see the mngt(9DDI) man page.

Diagnostics DDI

The diagnostic DDI allows a client to perform off-line tests on devices. This interface is typically provided by special diagnostic drivers to be started on inactive device nodes (failed or backup devices). For more information, see the diag(9DDI) man page.

Fault Injection DDIs

The fault injection bus drivers verify that a device driver is resilient to hardware faults. They help to build and validate hardened device drivers. Three new fault injection DDIs are provided:

Bus fault injection driver
PCI fault injection driver
ISA fault injection driver

For more information, see the busFi(9DDI), pciFi(9DDI), and isaFi(9DDI) man pages.

Statistic DDIs

The statistic DDIs are structure definitions used by the management DDI. They enable a client of a driver that exports the management DDI, to retrieve on demand raw I/O statistics since the driver last started. The following new statistics DDIs are provided:

DiskStat
EtherStat
FlashStat
UartStat

For more information, refer to the diskStat(9DDI), etherStat(9DDI), flashStat(9DDI), and uartStat(9DDI) man pages.

Changes to DKI Extensions

This section lists the changes to the DKI extensions.

svDkiThreadCancel

This new DKI call enable you to cancel the handler execution previously requested via svDkiThreadTrigger.

svDeviceNewNotify/svDeviceNewCancel

These new DKI calls enable you to connect/disconnect a handler which is invoked each time a new device driver instance is registered.

svDkiIoRemap

This new DKI call enables you to change the initial mapping of the device used by the debug agent which provides the console I/O. This call is typically used when the I/O device is located behind a bridge and the configuration of the bridge has changed.

svDkiInitLevel

The svDkiInitLevel call enables a driver to detect whether it is executing at microkernel initialization time or at runtime. In addition, the function allows a driver to determine whether it is runnning at critical or normal initialization step. This allows you to adapt the driver behavior according to the execution environment (critical/normal initialization or runtime).

High Resolution Timer DKI

The High Resolution Timer provides access to a fined-grained counter source for applications. This counter can be used for functions such as fine grained ordering of events or measurements of short segments of code. For more information, refer to the hrt(9DKI) man page.

Chapter 11 Changes to Drivers

This chapter illustrates the changes made to the driver source tree and lists the new and updated drivers for version 5.0 of the ChorusOS operating system. An important global change concerns the creation of a single driver actor for all drivers. This change has been made to improve memory footprint.

Reorganization of the Driver Source Trees

The driver source tree has been reorganized to reduce the existing driver components (DRV and DRV_F) to one generic DRV component. To make this possible, the drv_f source trees have been moved to the drv source tree.

This change is indicated in Figure 11-1 and Figure 11-2.

Figure 11-1 Old BSP Source Tree

Figure 11-2 New BSP Source Tree

The src/family Imakefile is able to select the correct family-dependent tree at compile time, for example:

#define IHaveSubdirs

SUBDIRS_x86    = x86
SUBDIRS_ppc60x = powerpc
SUBDIRS_mpc860 = powerpc
SUBDIRS_mpc8260= powerpc
SUBDIRS_usparc = usparc

SUBDIRS = $(SUBDIRS_$(FAMILY))

New Drivers

This section lists the new drivers, categorized by platform.

Generic Drivers

The following table indicates the generic drivers that have been added in version 5.0 of the ChorusOS operating system. For more information on each driver, consult the corresponding man page.

Table 11-1 New Generic Drivers


Driver	Reference Man Page
ATA hard disk driver	atadisk(9DRV)
Bus communication multiplexor driver	busmux(9DRV)
DEC2155x PCI bus driver	dec2155x(9DRV)
EPFPLD watchdog driver	epfpld(9DRV)
Ethernet bus communication driver	buseth(9DRV)
FPGA multi-function driver (watchdog, flash control, HSC)	fpga(9DRV)
GPIO-based HSC driver	gpiohsc(9DRV)
I8042 keyboard/mouse driver	i8042(9DRV)
Intel 28 Fxxxx flash driver	intel28fxxx(9DRV)
Intel 8255x ethernet driver	e100(9DRV)
ISA fault injection driver	isaFi(9DRV)
ISA PIC (I8259) driver	i8259(9DRV)
Loopback communication driver	buscom_loopback(9DRV)
Open PIC (MPIC/EPIC) driver	openpic(9DRV)
PCI fault injection driver	pciFi(9DRV)
PCI host communication driver	pcicom_host(9DRV)
PCI resource manager auxiliary driver	pcimngr(9DRV)
PCI swap auxiliary driver	pciswap(9DRV)
PowerQuicc CPM timer driver	cpmTimer(9DRV)
PowerQuicc PIT timer driver	pitTimer(9DRV)
PowerQuicc watchdog timer driver	siuWdt(9DRV)
RAVEN watchdog timer driver	raven_wdtimer(9DRV)
RIO ethernet driver	rio(9DRV)
SYM5 3c8xx SCSI HBA driver	sym53c8xx(9DRV)
Transparent nexus communication driver	buscom_nexus(9DRV)
VT82C586 ATA HBA driver	vt82c586_ata(9DRV)
VT82C586 ISA bus driver	vt82c586(9DRV)
W83C553 ATA HBA driver	w83c553_ata(9DRV)
Z8536 GPIO driver	z8536(9DRV)

UltraSPARC Specific Drivers

The following table indicates the generic drivers that have been added in version 5.0 of the ChorusOS operating system. For more information on each driver, consult the corresponding man page.

Table 11-2 New UltraSPARC Specific Drivers


Driver	Reference Man Page
Software interrupt bench driver	bench_softint(9DRV)
CP1500 HSC driver	usparchsc(9DRV)

PowerPC Specific Drivers

The following table indicates the PowerPC specific drivers that have been added in version 5.0 of the ChorusOS operating system. For more information on each driver, consult the corresponding man page.

Table 11-3 New PowerPC Specific Drivers


Driver	Reference Man Page
Decrementor bench driver	bench_tbDec(9DRV)
FALCON memory controller, common bus and flash control driver	falcon(9DRV)
HARRIER host PCI bus driver	harrier(9DRV)

Intel specific drivers

There are no new Intel-specific drivers in version 5.0 of the ChorusOS operating system.

Updated drivers

This section describes the existing drivers that have been changed in version 5.0 of the ChorusOS operating system.

Generic drivers

The following table lists the generic drivers that have been changed, along with a description of the changes made. For more information on each driver, consult the corresponding man page.

Table 11-4 Changes to Generic Drivers


Driver	Change	Reference Man Page
DEC2115x PCI-to-PCI bus driver	Supports the dynamic resource management using the PCI resource manager auxiliary driver. Supports cPCI hotswap using the PCI swap auxiliary driver and an HSC driver. Supports the bus communication framework using the transparent nexus communication driver. Provides the management DDI.	dec2115x(9DRV)
DEC2155x PCI-to-PCI bus driver	Supports the dynamic resource management using the PCI resource manager auxiliary driver. Supports cPCI hotswap using the PCI swap auxiliary driver and an HSC driver. Supports the bus communication framework using the transparent nexus communication driver.	dec2155x(9DRV)
DEC21x4x ethernet driver	Supports the DEC21143 ASIC with or without an external transceiver. Provides enhanced support for the 100 Mbps link. Supports ETHER_VERSION_1 DDI allowing DMA transfer directly to and from client frame buffers. Provides management and diagnostics DDIs. Hardened.	dec21x4x(9DRV)
Cheerio ethernet driver	Supports ETHER_VERSION_1 DDI allowing DMA transfer directly to and from client frame buffers. Provides the management and diagnostics DDIs. Supports TCP/UDP hardware checksum on reception and transmission. Hardened.	cheerio(9DRV)
AMD29xxx flash driver	Uses a flash control driver when available on a given platform.	amd29xxx(9DRV)
Z85x30 UART driver	Uses a GPIO driver (when available on a given platform) to manage the modem signal.	z85x30(9DRV)
Simba PCI-to-PCI bus driver	Supports dynamic resource management using the PCI resource manager auxiliary driver. Provides the management DDI. Hardened.	simba(9DRV)
M48Txx RTC driver	Supports the NVRAM DDI. Supports the watchdog timer DDI if the watchdog timer is supported by the chip.	m48txx(9DRV)
RIC driver	Hardened.	ric(9DRV)

UltraSPARC Specific Drivers

The SABRE PCI host bus driver has been hardened. For more information, refer to the sabre(9DRV) man page.

PowerPC Specific Drivers

The following changes have been made to the RAVEN PCI host bus driver:

Supports RAVEN and HAWK PCI host bridges using the Open PIC and FALCON auxiliary drivers.
Supports the dynamic resource management using the PCI resource manager auxiliary driver.
Provides the management DDI.
Hardened.

For more information, see the raven(9DRV) man page.

Intel Specific Drivers

No changes have been made to the Intel specific drivers.

Chapter 12 Changes to Boot Libraries and Boards

This chapter lists the changes made to the boot library and to the boards in version 5.0 of the ChorusOS operating system.

Boot Library Changes

In previous versions of the ChorusOS operating system, the boot_tools library was used by the bsp component only. This library has therefore been moved to the nucleus/bsp/src source tree.

The bki library was previously used by both the bsp component and the microkernel. This library has been duplicated into the nucleus/bsp source tree.

The new layout of the bsp/src tree is shown in Figure 12-1.

Figure 12-1 New bsp/src Tree

Board Changes

Where possible, boards with similar BSPs have been merged to share source code. As a result, device trees and the debug agent driver can be tuned at runtime, if the boot can determine on which board it is running.

On powerpc boards, the board can be identfied by reading a well-known register. A system image can therefore run without any modification on multiple board types. The drawback is that the system image must contain all the drivers for all boards.

On boards which do not have this hardware identification, a mechanism using xml definitions and environment variables can be used. In this case, the system image must be configured for a specific board. The advantage of this approach is that drivers can also be tuned for a board. The following sections describe the board changes that have been implement in the source tree of version 5.0.

x86 Boards

The i386at and cpn5360 BSPs have been merged into a new pc BSP. (Support for the cpn5360 board is new in version 5.0 of the ChorusOS operating system). Because the boot is unable to detect the board on which it is running, a TARGET xml definition has been added.

The TARGET definition can take one of two values: PC_AT or CPN5360. The default value is PC_AT.

To build a chorus system image for a CPN5360 target:

% configurator -set TARGET=CPN5360
% make chorus

PowerPC Boards

The mcp750, mcpn750 and mcpn765 BSPs have been merged into the new mcp7xx BSP. The boot can detect on which board it is running.

Support for the PowerPC 74x0 processor is also new in version 5.0. The new board for this processor is mcpn765.

Usparc Boards

The cp1500 BSP has been moved to the cpxxxx directory and has been adapted to support the new CP2000 and AX boards.

Because the boot cannot detect on which board it is running, a TARGET xml definition has been added. The TARGET definition can take one of three values: CP1500, CP2000, or AX1105. The default value is CP1500.

To build a ChorusOS system image for a CP2040, CP2060, or CP2080 target use the following:

% configurator -set TARGET=CP2000
% make chorus