test

ChorusOS 5.0 Board Support Package Developer's Guide

The Boot-Kernel Interface

This section describes the Boot-Kernel interface, including both common and target specific BKI.

The Boot-Kernel interface (BKI) is a set of rules used when the kernel is launched. Part of the BKI is common to all target families, and part of it is specific to a given family. A family-specific BKI can define a number of dialects. The microkernel binary must be configured to understand the dialect required by the bootstrap program.

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 structure 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 structure must be in the following state:

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. Each device node has some generic and some specific properties associated with it. 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 Chapter 9, Driver Kernel Interface Overview 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 code Example 4-13.

Example 4-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:

PowerPC BKI

This section details the state that the CPU should be in for PowerPC BKI acceptance.

Note -

For historical reasons, the naming convention for PowerPC BKI constants uses PPC60x, instead of PowerPC. The original PowerPC BKI was written for the PPC60x PowerPC BKI, however, all PowerPC processor families (8xx, 8260, 60x) now share the same BKI.

x86 BKI

This section details the state that the CPU should be in for the x86 BKI.

The BootConf structure pointer is pushed onto the stack before calling the microkernel entry point.

Interrupts must be disabled.

The processor must be in protected mode, and all the segments must cover the entire address space.

Translation must be disabled.

UltraSPARC IIi BKI

This section details the state that the CPU should be in for the UltraSPARC IIi BKI.

Register %o0 must contain a pointer to the BootConf structure.

Interrupts must be disabled.

Instruction and data caches must be disabled.

At address 0, a minimal trap table must be installed with spill/fill trap handlers.

MMU translation must be enabled.

An initial one-to-one mapping must be built by the boot program. This one-to-one mapping must start at 0 and be large enough to cover all virtual addresses for the memory bank's binary segments. Note that instruction and data Translation Lookaside Buffer (TLB) mapped in this way will initially be locked and all TLB entries not included in the initial mapping will be invalid.

The kernelSpace field in the BootConf structure must point to a description of the initial space established by the microkernel's memory management unit, as described in "The Initial Address Space". The family-dependent part of the tag field of the PhChunk entry is defined as a combination of the following bits:

Table 4-2 PhChunk KSP Region Type
PhChunk Bit Meaning
KSP_US_TYPE_RAM one-to-one RAM mapping

Table 4-3 PHChunk Data Attributes
PhChunk Bit Meaning
KSP_US_ATTR_DG   global
KSP_US_ATTR_DW writable
KSP_US_ATTR_DP privileged
KSP_US_ATTR_DE side effect
KSP_US_ATTR_DCV  cached virtually
KSP_US_ATTR_DCP cached physically (L2-cache)
KSP_US_ATTR_DIE inverted endiannes
KSP_US_ATTR_DNFO non faulted only
KSP_US_ATTR_DV valid

Table 4-4 PHChunk Instruction Attributes
PHChunk Bit Meaning
KSP_US_ATTR_IG   global
KSP_US_ATTR_IV valid
KSP_US_ATTR_IP privileged
KSP_US_ATTR_ICP  cached physically (L2-cache)

The initial kernel space must at least contain the one-to-one mapping of the available RAM.

The f_bootConf field of the BootConf structure must point to a processor specific decriptor:

typedef struct usparc_BootConf {

    VmAddr    tlb_lock_start; /* start, size and attributes of the memory */
    VmSize    tlb_lock_size;  /* region locked in I and D TLB by          */
    int       tlb_lock_attr;  /* the bootstrap program                    */

    VmAddr    trap_table_start; /* address of the trap table */

  } usparc_BootConf;

The first three fields decribe the initial one-to-one mapping. The last one gives the address of the trap table. The SPARC_PROP_I_CACHE and SPARC_PROP_D_CACHE properties must be present in the initial device tree. Values for these properties are of the type SparcPropCache:

typedef struct {
    uint32_f  csize;          /* cache size */
    uint32_f  bsize;          /* cache bank size */
    uint32_f  lsize;          /* cache line size */
    uint32_f  nbanks;         /* number of bunks (csize = bsize * nbanks) */
    uint32_f  type;           /* cache type */
  } SparcPropCache;