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.
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.
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.
/* * 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.
This section details the state that the CPU should be in for PowerPC BKI acceptance.
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.
Register r3 must contain a pointer to the BootConf
structure.
External interrupts must be disabled.
Instruction and data translations must be disabled.
Internal (L1) memory cache must be disabled.
The MMU must be disabled; all MMU's registers and Translation Lookaside Buffer (TLB) entries, if any, must be in a reset/disabled/invalidated state.
The processor must be in Supervisor privilege state.
Machine-check exceptions must be enabled.
The processor must be in a recoverable exception state.
Floating point instructions must be disabled.
The kernelSpace field
in the BootConf
object must point to a description of the initial
space that must be 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:
KSP_PPC60x_BAT bit specifies that the mapping
must be established using two Block Address Translation (BAT) registers. In
this case, the mapping specified by PhChunk
(the physical address,
the corresponding virtual address and the size) must be properly aligned as
required by the PowerPC 60x specifications. The microkernel will establish
the required mapping in one data BAT (DBAT) and one instruction BAT (IBAT).
Therefore, only four kernelSpace entries can have
BAT mappings. If the KSP_PPC60x_BAT bit is not specified, the microkernel
uses page address translations to establish the required mapping.
KSP_PPC60x_W bit specifies that the write-through memory access attribute must be set in the corresponding BAT or PTEs.
KSP_PPC60x_I bit specifies that the caching-inhibited memory access attribute must be set in the corresponding BAT or PTEs.
KSP_PPC60x_M bit specifies that the memory coherency memory access attribute must be set in the corresponding BAT or PTEs.
KSP_PPC60x_G bit specifies that the guarded memory access attribute must be set in the corresponding BAT or PTEs.
KSP_PPC60x_RW bits specify that read and write access are allowed.
KSP_PPC60x_RO bits specify that only read access is allowed.
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.
This section details the state that the CPU should be in for the UltraSPARC IIi BKI.
Register I/O 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 Table Look-up Buffers (TLBs) mapped in this way will intially be locked and all TLB entries not included in the initial mapping will be invalid.
The kernelSpace field in the BootConf
object 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:
PhChunk
KSP region typePhChunk Bit | Meaning |
---|---|
KSP_US_TYPE_RAM | one-to-one RAM mapping |
Table 3-3
PHChunk
Data attributesPhChunk 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 3-4
PHChunk
Instruction attributesPHChunk 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;