Common BKI

The bootstrap program must transfer control to the microkernel entry point, passing, in a register, a pointer to an object of type BootConf (see "bootconf Structure"). The register name or number is defined by the family-specific BKI. The BootConf object and all objects that it points to must be accessible for both reading and writing.

The microkernel code assumes that all text and data are already at the correct execution addresses, that the data is writable, and that non-initialized data is already set to zero.

All interrupts must be disabled at the CPU level before the bootstrap program transfers control to the microkernel. The microkernel assumes that all available memory caches that can be disabled are already disabled and have been properly flushed.

The microkernel does not expect a valid program stack from the bootstrap program.

The BootConf object must be in the following state:

• binDesc must describe the binaries of the microkernel and of all drivers and actors that the microkernel will launch. The microkernel assumes that all segments of type SEG_KSP are already installed at their execution addresses and that the segment's zero-initialized data is already set to zero. binDesc can contain descriptors of other binaries. See "Binaries" for more information about binDesc.

• ramAllocator must tag as RAM_FREE the portions of RAM available for immediate allocation. All other RAM must be tagged as RAM_ALLOCATED. When the system initialization procedure no longer requires the BootConf object, the microkernel can reuse the RAM occupied by binaries of the types BIN_BOOTSTRAP and BIN_BOOTCONF.

Initial Device Tree

The device tree is a data structure that describes hardware topology and device properties. The hardware topology is specified in terms of parent/child relationships. Device properties associated with each device node in the tree are device specific. A device property is a name/value pair. The property name is a null-terminated ASCII string. The property value is a sequence of bytes specified by a length/address pair.

The initial device tree is built by the bootstrap program using the DKI tree browsing API. See ChorusOS 4.0 Device Driver Framework Guide for information about the DKI interface and the device tree.

Generic device node properties used by the microkernel are defined in ddi/prop.h, as shown in Example 3-13.

Example 3-13 Properties Defined in ddi/prop.h

/*
 * Generic properties:
 *
 *    The "byte-order" property specifies the byte ordering on cpu/bus.
 *      name:      PROP_BYTE_ORDER
 *      value:     PropByteOrder
 *      constants: BYTE_ORDER_BIG    - big-endian byte order
 *                 BYTE_ORDER_LITTLE - little-endian byte order
 *
 *    The "clock-freq" property specifies the CPU/bus clock frequency in Hz.
 *      name:      PROP_CLOCK_FREQ
 *      value:     PropClockFreq
 *
 *    The "active" property flags active device nodes, i.e. devices
 *    which are already serviced by drivers.
 *      name:      PROP_ACTIVE
 *      value:     -
 *
 *    The "driver" property specifies the name of driver which should be
 *    binded to the node:
 *      name:      PROP_DRIVER
 *      value:     char[] (NULL terminated ASCII string)
 *    
 *    The "system-tick" property flags a timer device node which
 *    is assigned to the system tick.
 *      name:      PROP_SYSTEM_TICK
 *      value:     -
 *
 *    The "perf-tick" property flags a timer device node which is
 *    assigned to the PERF module.
 *      name:      PROP_PERF_TICK
 *      value:     -
 *
 *    The "prof-tick" property flags a timer device node which is
 *    assigned to the PROF module.
 *      name:      PROP_PROF_TICK
 *      value:     -
 *
 *    The "ram-size" property specifies the amount of available RAM memory
 *      name:      PROP_RAM_SIZE
 *      value:     PhSize
 *
 *    The "family" property specifies the name of the product family
 *      name:      PROP_FAMILY
 *      value:     char[]
 *
 *    The "platform" property specifies the name of the target platform
 *      name:      PROP_PLATFORM
 *      value:     char[]
 *
 *    The "cache-size" property specifies the size of the L2 cache
 *      name:      PROP_CACHE_SIZE
 *      value:     PropCacheSize
 *
 *    The "banks" property specifies the physical memory layout
 *      name:      PROP_BANKS
 *      value:     PhChunk[]
 *
 *    The "timer-freq" property specifies the frequency of a
 *    given timer.
 *      name:      PROP_TIMER_FREQ
 *      value:     PropTimerFreq
 *
 *    The "dbg-link" property flags a device node which is assigned to
 *    the debugging agent.
 *      name:      PROP_DBG_LINK
 *      value:     -
 */

#define PROP_BYTE_ORDER         "byte-order"
#define PROP_CLOCK_FREQ         "clock-freq"
#define PROP_ACTIVE             "active"
#define PROP_DRIVER             "driver"
#define PROP_SYSTEM_TICK        "system-tick"
#define PROP_PERF_TICK          "perf-tick"
#define PROP_PROF_TICK          "prof-tick"
#define PROP_SYSTEM_PIC         "system-pic"
#define PROP_RAM_SIZE           "ram-size"
#define PROP_FAMILY             "family"
#define PROP_PLATFORM           "platform"
#define PROP_CACHE_SIZE         "cache-size"
#define PROP_BANKS              "banks"
#define PROP_TIMER_FREQ         "timer-freq"
#define PROP_DBG_LINK           "dbg-link"
#define PROP_SYSTEM_SPEAKER     "system-speaker"

typedef uint32_f PropByteOrder;

#define BYTE_ORDER_BIG          0x00010203      /* big-endian */
#define BYTE_ORDER_LITTLE       0x03020100      /* little-endian */

typedef uint32_f PropClockFreq;
typedef uint32_f PropTimerFreq;

typedef PhSize   PropRamSize;

typedef uint32_f PropCacheSize;

    /* Values for PROP_NODE property, common to all architectures */
#define NODE_ROOT               "local-bus"
#define NODE_CPU                "cpu"
#define NODE_MEM                "ram"
#define NODE_L2_CACHE           "l2-cache"

Family specific properties are defined in ddi/ddi_f.h.

The microkernel requires that the device tree contains the following device nodes and properties:

• The root node must be defined and have the following properties:

  • PROP_NODE must have the value NODE_ROOT.

  • PROP_FAMILY must be defined and identify the processor family. The value of the property is a family-dependent string, such as FAMILY_POWERPC or FAMILY_INTEL.

  • PROP_PLATFORM must be defined and identify the board. The value is a platform-dependent string, such as "Motorola Genesis 2 family" or "Intel x86 PC/AT".

• The cpu node must be defined and have the following properties:

  • PROP_NODE must have the value NODE_CPU.

  • PROP_CLOCK_FREQ specifies the CPU clock frequency. Its value is of type PropClockFreq.

• A time device node with the PROP_SYSTEM_TICK property must be defined, to describe the system clock.

• Optionally, a second time device node with the PROP_PERF_TICK property can be used by the microkernel for benchmarks.