Chapter 2 Building a ChorusOS SystemThis chapter describes how to build your ChorusOS operating system for your chosen target.
Creating the System ImageThis section explains what the system image is and how to create it using the tools provided. The system image is the initial state of the target board's physical memory. It contains a set of files organized in one or more memory banks. When the target system is deployed, some of the system image memory banks are burnt into non-volatile physical memory. The rest can be downloaded from a local device or from the network by the initial loader. To build the system image, you use an XML-based system. This system has two components:
The configuration must specify the list of memory banks and, for each particular bank, a symbolic name, a base address, and a size limit. Also, the configuration can request mkimage to organize any particular memory bank as a file system volume. The current ChorusOS operating system release supports FAT MS-DOS format only. The configuration must also specify a list of files to be included in the system image and, for each particular file, the bank where the file must be stored. In addition, for relocatable ELF files, the configuration can specify how the file must be relocated when stored in the memory bank. Relocating ELF FilesIf relocation is specified for a given file, mkimage relocates it and stores the resulting absolute binary file in the memory bank. You can specify how many program segments must contain the resulting binary file and, for each individual segment, how it must be relocated. A segment can be relocated into a linking area or to the segment image's base address within the memory bank. A linking area is a named range of addresses specified by an id, a base address, and a size. You can specify a different linking area for each program segment. mkimage relocates a segment to the lowest available range of addresses of a suitable size within the linking area. mkimage guarantees that different segments relocated to the same linking area will never overlap. However, segments relocated to overlapping linking areas can overlap. Execution in Place (XIP)For any particular segment you can specify whether the segment must be executed at its place within the memory bank (in this document this segment is refered to as the "XIP segment") or whether it must be copied into the RAM before it is executed. bootconf BinaryThe mkimage command builds a binary file called bootconf. The bootconf file contains a data structure called BootConf, which describes the system image contents and layout. mkimage includes the bootconf binary file in one of the system image memory banks. The initial loader boots the ChorusOS operating system, jumping to the entry point of bootconf binary. bootconf is a board-independent program that gets control from the board-specific initial loader and transfers control to the board-specific bootstrap program. In some cases, the initial loader needs to pass a board-dependent parameter to the bootstrap. This parameter can be loaded into a specific CPU register, and bootconf passes the entry value of the register to the bootstrap program as an opaque parameter. The register is: When the bootconf binary is entered, it sets up a program stack in a stack area within its data segment, finds the descriptor of the bootstrap binary in the BootConf structure, and jumps to this entry point, passing the following parameters:
To jump to the bootstrap entry point, bootconf uses the standard C function invocation conventions. The bootstrap entry point is: typedef void (*BootEntry) (struct BootConf*, void* cookie); bootconf StructureThe bootconf file contains an object of type typedef struct BootConf {
unsigned int stamp; /* identification stamp */
PhMap* kernelSpace; /* initial address space descriptor */
VmAddr spaceBarrier; /* frontier between user and supervisor
address space */
int numBanks; /* number of system image memory banks */
BankDesc* bankDesc; /* system image memory bank descriptors */
int numBins; /* number of binaries */
BinDesc* binDesc; /* array of binary descriptors */
int numSegs; /* number of segments */
BinSegDesc* segDesc; /* array of segment descriptors */
RamDesc ramAllocator; /* ram occupation */
KnSymbolTable* symbols; /* symbols for kdb */
EnvDesc* env; /* environment descriptor */
void* heapStart; /* memory heap: */
void* heapCur; /* occupied from heapStart to heapCur */
void* heapLimit; /* available from heapCur to heapLimit */
unsigned int siteNumber; /* site number used for remote IPC */
DevNode rootDevice; /* device tree */
IdleFunc idleFunc; /* function to be executed in the idle loop */
DbgBsp dbgBsp; /* bsp for Debug Agent */
DbgOps dbgOps; /* debug Agent interface */
BootConfRebootEntry rebootEntry; /* reboot entry */
RebootDesc* rebootDesc; /* reboot descriptor */
void* f_bootConf; /* a processor-specific descriptor */
} BootConf;
Example 2-1 contains an example of a BootConf structure. The Initial Address SpacekernelSpace describes the initial address space. The exact interpretation of this descriptor is architecture dependent:
Other architecture-dependent requirements for the initial address space layout may be specified. See "The Boot-Kernel Interface (BKI)" for details. If required, the initial virtual address space is specified by the PhMap structure: typedef struct PhChunk {
PhAddr start; /* chunk physical start address */
PhSize size; /* chunk size in bytes */
unsigned int tag; /* chunk attributes */
} PhChunk;
typedef struct PhMap {
int numChunks; /* number of items in the array */
PhChunk* chunk; /* array of chunk descriptors */
} PhMap;
PhMap and PhChunk
are declared in ~nucleus/src/lib/bki/phMap.h and ~nucleus/src/lib/bki/phChunk.h respectively. The PhMap structure is a series of If the tag value in Otherwise, the start field of a The value of the spaceBarrier field may influence the dimensions of the supervisor and the user virtual address spaces. The exact meaning of this field is architecture dependent (see "The Boot-Kernel Interface (BKI)" for details). BanksThe bankDesc structure points to an array of typedef struct BankDesc {
char* id; /* bank's symbolic name */
BankType type; /* bank's type */
char* fs; /* files system type symbolic name */
VmAddr vaddr; /* address required for the bank's image */
VmSize size; /* bank's size */
} BankDesc;
The bankDesc structure is declared in ~nucleus/sys/common/src/lib/bki/bki.h. A memory bank is specified by vaddr, indicating the starting address within the initial address space, and size. The type field value is a combination of the bits listed in Table 2-1. Table 2-1 type Bits
If any of the last three bits is set, the BANK_DEVICE bit must also be set. Files in a memory bank can by organized as a volume of a file system. In this case, the fs field points to a stiring containing the name of the file system type (for example, "FAT" stands for MS-DOS FAT files system). Otherwise, fs is 0. When the initial loader jumps to the bootconf entry point, the memory banks containing the BIN_BOOTCONF and BIN_BOOTSTRAP program binaries must already be installed at the address indicated by vaddr. When the bootstrap program transfers control to the microkernel, all memory banks must be installed at the address indicated by vaddr. BinariesThe binDesc array points to an array of typedef struct BinDesc {
char* name; /* binary symbolic name */
int firstSeg; /* first segment index */
int lastSeg; /* last segment index */
KnPc entry; /* binary entry point */
BinType type; /* binary type */
BinMode mode; /* binary loading mode */
void* actor; /* private for the u-kernel */
} BinDesc;
Each binary is composed of a set of segments. The firstSeg and lastSeg fields specify the range
of segments within the array of segment descriptors, pointed to by segDesc, that store the binary described by The type field specifies the binary's type and is set to one of the binType values listed in Table 2-2. Table 2-2binType Values
The mode specifies the binary activation mode and can be any combination of the BinMode flags listed in Table 2-3. Table 2-3BinMode Flags
These flags only have meaning for BIN_SUPERVISOR and BIN_USER binaries. The value of mode is ignored for all other binary types. numBins specifies the number of elements in the array pointed to by binDesc.
segDesc points to an array of segment descriptors.
Each item in the array is a typedef struct SegDesc {
VmAddr kaddr; /* image address */
VmAddr vaddr; /* execution address (from link editor) */
VmSize ksize; /* image size */
VmSize vsize; /* execution size */
SegType type; /* code or data */
SegSpace space; /* address space type */
} SegDesc;
The descriptor specifies two things:
The segment image is stored in the memory bank containing the segment's
binary. When the memory bank is installed at the required address, as specified
in the When executed, the segment must be installed at the address specified by the vaddr field and its size must be equal to vsize. If vsize is greater than ksize, the memory from vaddr+ksize to vaddr+vsize must be initialized to zero. The space field indicates whether a segment belongs to the initial address space. It can be set to one of the values listed in Table 2-4. Table 2-4SegSpace Values
Only binaries of the BIN_ACTOR type can hold SEG_VIRTUAL segments. The value of the type field can be any combination of the bits listed in Table 2-5. Table 2-5 SegType Bit Values
If a segment is executable in place (XIP), and belongs to the initial kernel address space (for example, the SEG_XIP bit is set in the type field and the space field is equal to SEG_KSP), the segment's execution address will be the same as the segment's image address and the segment's execution size will be equal the segment's image size. Therefore, when a memory bank is installed at the address specified by its descriptor (BankDesc::vaddr), all XIP KSP segments that belong to the memory bank will have no particular installation procedure and will be ready for execution.
numSegs specifies the number of elements
in the array pointed to by RAM OccupationramAllocator describes RAM occupation by the system image. The mkbootconf tool initializes the ramAllocator state. It tags as allocated the memory dedicated to:
The ChorusOS operating system provides a library of functions to manipulate
the Environment Variablesenv points to an EnvDesc structure. EnvDesc is declared in ~nucleus/sys/common/src/lib/util/env.h. typedef struct EnvDesc {
int envSize; /* current size of environment */
int envMaxSize; /* memory available for environment */
char* envPtr; /* pointer to the environment */
} EnvDesc;
The system image contains a data file with the
initial state of the system environment variables. The env
field of the envPtr points to a sequence of environment variable definitions. Each definition is a concatenation of two strings, envVariable and envValue, where envVariable is the null-terminated string name of an environment variable, and envValue is the null-terminated string value of the environment variable. envSize is the size in bytes of the environment variable definition sequence. envMaxSize is the environment file size. envSize must not exceed envMaxSize. Heap and StackheapStart points to the beginning of a block of statically allocated memory. The block can be used by the bootstrap program for dynamic memory allocation. For instance, the heap is used by the device tree library memory allocator (see "Initial Device Tree") to build the initial state of the board's device tree. heapCur points to the first byte available for future allocation. mkbootconf sets heapCur to heapStart. heapLimit points to the heap memory limit. The size of the heap memory is equal to heapLimit-heapStart. The heap is also used for the initial stack. The bootconf startup procedure initializes the current stack pointer with the heapLimit value. All other fields of the BootConf structure are initialized dynamically during the system bootstrap. Example BootConf StructureThis section contains an example of a Example 2-1
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
