ChorusOS 4.0 Porting Guide

Chapter 5 System Image Configuration

This chapter explains how to define the system image configuration, in a set of configuration files. These configuration files are created in XML.

Overview

You cannot use the graphical configuration tools, ews, to define the system image configuration for a new target board. Instead, create the configuration files using a text editor. Once the files have been created, you can view them using ews, and build the system image. You can also use the mkimage tool to build the system image.

The board-specific configurations must be stored in the directory src/nucleus/bsp/family/board. For example, the board-specific configuration files for the SBC8260 board are stored in src/nucleus/bsp/powerpc/sbc8260, and those for the PC/AT are stored in src/nucleus/bsp/x86/i386at.

There are two configuration files:

target.xml specifies the main board-specific configuration.
target_action.xml specifies the board-specific system image reshaping procedure.

Most of the examples in this chapter use the SBC8260 board. To understand the examples, the following information about the SBC8260 board is useful:

CPU: EC603e
Physical memory map: The powerup initialization code programs the chipset memory map decoder registers in such a way that in the processor's physical address space all available RAM is contiguously mapped to (physical) address 0x0, and at least 1M of NOR flash memory is contiguously mapped to the end of the physical address space (that is, to the physical address 0xfff00000).
Deployment: The ChorusOS configuration supports two deployment schemes:
- Boot from ROM
  
  Write the ChorusOS operating image to flash memory and then boot the ChorusOS operating system from flash memory, by resetting the board.
- Boot from RAM
  
  Write the ChorusOS Boot Monitor to flash memory and then download the ChorusOS operating system image from the network to RAM.

Imported Objects

The following objects are pre-defined and can be used within the board-specific configuration files:

SYSTEM specifies the kind of ChorusOS operating system currently built and is an enumeration. The possible values of SYSTEM are:
- kernonly: the system image will contain the micro-kernel, built-in drivers and possibly built-in application actors
- chorus: the system image will contain the micro-kernel, built-in drivers, the POSIX personality and possibly built-in application actors
- uartTest or flashTest: the system image will contain the corresponding device driver (UART or flash memory) test program
- kts or ktu: the system image will contain the general purpose micro-kernel test suite to be run in the supervisor (kts) or the user (ktu) mode
- benchs or benchu: the system image will contain the micro-kernel benchmark program to be run in the supervisor (benchs) or the user (benchu) mode
BOOT_MODE specifies how the generated system image will be deployed on the target board, and is an enumeration. The possible values for BOOT_MODE are:
- ROM: the system image will be deployed (burned, flashed) in ROM or flash
- RAM: the system image will be downloaded in RAM from a local device or the network
BUILD_DIR is a string specifying the build directory prepared by the configure utility during the ChorusOS operating system installation.
BSP_DIR is a string specifying the installation directory of the BSP configuration and bootstrap package.
DRV_F_DIR is a string specifying the installation directory of the Family-specific drivers package.
DRV_DIR is a string specifying the installation directory of the Generic drivers package.

target.xml Definition

A target.xml file contains a number of hierarchical folders:

Global variables
Banks
Areas
Kernel address space
Link-edit models
Files
System image, which contains the following folders:
- Files
- Auto-generated files
- Miscellaneous

Global Variables

The global variables folder contains definitions of global system image configuration variables.

Some of them are board-specific and used within the board-specific configuration files only. For example, a configuration for a PC/AT target defines the LOADER configuration variable, with a value specifying which of the two initial loaders (SVR4 boot and Linux LILO boot) will be used to load the system image. The format of the system image is tailored to match the requirements of the initial loader specified by LOADER.

There is one mandatory global variable, IMAGE_DIR. This variable specifies the working directory to be used by the mkimage tool to store the files created during system image generation.

Example 5-1 is an extract of the SBC8260 board-specific configuration file, and defines two global configuration variables, IMAGE_DIR and RESULT.

Example 5-1 SBC8260 Global Variable Configuration

<definition name='IMAGE_DIR'>
			<description>'mkimage' tool output repository</description>
			<string/>
			<vstring>${BUILD_DIR}/image/${BOOT_MODE}/${SYSTEM}</vstring>
</definition>

<definition name='RESULT'>
			<description>the resulting system image file pathname</description>
			<string/>
			<vstring>${BUILD_DIR}/${SYSTEM}.${BOOT_MODE}</vstring>
</definition>

The value of IMAGE_DIR specifies the mkimage working directory as a function of the BOOT_MODE and SYSTEM configuration variables. For example, the working directory for RAM-based chorus system image generation is ${BUILD_DIR}/image/RAM/chorus.

The value of RESULT specifies the filename of the resulting (bootable) system image file. The filename also depends on the BOOT_MODE and SYSTEM configuration variables. For example, the bootable RAM-based chorus system image file will be stored in ${BUILD_DIR}/chorus.RAM.

Banks

The banks folder contains definitions of the system image memory banks.

A system image memory bank is specified by an object of the type Bank. The following fields of a Bank object are defined in a target.xml file:

addr is an integer specifying the address at which the memory bank must be installed (burned or downloaded) during the system deployment process. Usually the address is physical on PowerPC and x86 systems and virtual in UltraSPARC systems.
size is an integer specifying the maximum size of the memory bank.
ram is a boolean specifying whether the bank occupies RAM at installation.

If the value of ram is true, mkimage determines the portion of the system RAM that the memory bank image will occupy after installation, and tags that RAM as PH_ALLOCATED in the initial state of the RAM allocator.

If the value of ram is false, the bank has no impact on the initial state of the RAM. For example, the value of ram must be false if the memory bank is to be burned in ROM.

The default value of ram is true.

The board-specific configuration can define any number of memory banks. A board-specific configuration must define a Bank object named sys_bank.

For example, the SBC8260 board-specific configuration defines two memory banks trampoline_bank and sys_bank.

trampoline_bank will contain the power-up initialization (trampoline) program (see "Power-up Program Implementation"). sys_bank will contain the remains of the system image.

Example 5-2 is an extract of the SBC8260 board-specific configuration file, and defines the trampoline_bank and sys_bank objects.

Example 5-2 SBC8260 Bank Configuration

	
<folder name='Banks'>

    <description>system image memory banks</description>

    <definition name='sys_bank'>
      <description>default system image memory bank</description>
      <condition>
        <equal><var name='BOOT_MODE' /><const>RAM</const></equal>
      </condition>

      <type name='Bank' />
      <value field='ram'><true /></value>
      <value field='addr'><const>0x00100000</const></value>
      <value field='size'><const>0x00f00000</const></value>
    </definition>

    <definition name='trampoline_bank'>
      <description>memory bank for a 'trampoline' (eg. power-up) binary</description>
      <condition>
        <equal><var name='BOOT_MODE' /><const>ROM</const></equal>
      </condition>
      <type name='Bank' />
      <value field='ram'><false /></value>
      <value field='addr'><const>0xfff00000</const></value>
      <value field='size'><const>0x00001000</const></value>
    </definition>

    <definition name='sys_bank'>
      <description>default system image memory bank</description>
      <condition>
        <equal><var name='BOOT_MODE' /><const>ROM</const></equal>
      </condition>
      <type name='Bank' />
      <value field='ram'><false /></value>
      <value field='addr'><const>0xfff01000</const></value>
      <value field='size'><const>0x000ff000</const></value>
    </definition>

  </folder>

Two bank configurations are provided. The first configuration is used when the system is configured to boot from ROM. This configuration is selected when the value of the BOOT_MODE configuration variable is set to ROM. In this case, trampoline_bank will start at the address 0xfff00000 and can contain up to 4K bytes, sufficient for thetrampoline program to run. sys_bank starts immediately after trampoline_bank at the address 0xfff01000 and it can contain up to 0xff000 bytes.

The second configuration is used when the system is configured to boot from RAM. In this case, trampoline_bank is not defined. sys_bank starts at the address 0x00100000 and it can contain up to 0xf00000 bytes. The RAM occupied by the bank will be tagged as allocated when the initial state of the RAM allocator is generated, because the value of the ram field is true.

Areas

This folder contains definitions of the linking areas used during system image link-edit. A linking area is specified by an object of the type Area which defines the following fields:

addr is an integer specifying the starting address of the linking area. The address can be physical or virtual on PowerPC and x86 based systems and is usually virtual on UltraSPARC based systems.
size is an integer specifying the size of the linking area.
virtual is a boolean specifying whether the linking area occupies virtual address space. If the value of virtual is false, mkimage determines the portion of the system RAM that the segments link-edited into this area will occupy and tags the RAM as PH_ALLOCATED in the initial state of the RAM allocator.

If the value of virtual is true, the area will not impact the initial state of the RAM allocator. For example, the value of virtual must be true when the area object corresponds to a portion of a user virtual address space.
private is a boolean specifying whether or not the linking area is shared. If the value of private is false, the linking area is shared by all binaries that use it. This means that any two segments link-edited into this area will not overlap. These types of linking areas are typically used to link-edit supervisor address space binaries.

If the value of private is true, one instance of the linking area is created for each binary that uses it. This means that two segments link-edited into this area overlap if, and only if, they belong to two different binaries. These types of linking areas are typically used to link user address space actors.

The board-specific configuration can define any number of linking areas. A board-specific configuration must define an Area object named ram_area.

For example, the SBC8260 board-specific configuration defines three linking areas: ram_area, supervisor_actor_area, and user_actor_area.

When the micro-kernel is configured with the memory management module implementing the flat memory model (that is, when the value of the VIRTUAL_ADDRESS_SPACE configuration variable is false), only ram_area is defined. It is used to link-edit all non-XIP data segments.

Example 5-3 is an extract of the SBC8260 board-specific configuration file, and defines the ram_area object.

Example 5-3 SBC8260 ram_area Configuration

    <definition name='ram_area'>
      <description>default system image linking area
          (used for bss only)</description>
      <condition>
        <equal><var name='BOOT_MODE' /><const>RAM</const></equal>
      </condition>
      <type name='Area' />
      <value field='addr'><const>0x00004000</const></value>
      <value field='size'><const>0x000fc000</const></value>
      <value field='private'><false/></value>
      <value field='virtual'><false/></value>
    </definition>

    <definition name='ram_area'>
      <description>default system image linking area
          (used for data segments)</description>
      <condition>
        <equal><var name='BOOT_MODE' /><const>ROM</const></equal>
      </condition>
      <type name='Area' />
      <value field='addr'><const>0x00004000</const></value>
      <value field='size'><const>0x00ffc000</const></value>
      <value field='private'><false/></value>
      <value field='virtual'><false/></value>
    </definition>

When the microkernel is configured with one of the memory management modules implementing the virtual memory model (that is, when the value of the VIRTUAL_ADDRESS_SPACE configuration variable is true), three linking areas are defined:

ram_area has the same definition as described above but is used to link-edit BIN_STANDALONE binaries, such as bootconf and bootstrap programs, the debug agent and the micro-kernel, only.
supervisor_actor_area is used to link-edit all built-in drivers and supervisor actors.
user_actor_area is used to link-edit all user actors.

Example 5-4 is an extract of the SBC2860 board-specific configuration file, and defines the supervisor_actor_area and user_actor_area objects.

Example 5-4 SBC8260 supervisor_actor_area and user_actor_area objects

   <definition name='supervisor_actor_area'>
      <description>linking area for supervisor actors</description>
      <condition><var name='VIRTUAL_ADDRESS_SPACE' /></condition>
      <type name='Area' />
      <value field='virtual'><true /></value>
      <value field='private'><false /></value>
      <value field='addr'><const>0xa0000000</const></value>
      <value field='size'><const>0x40000000</const></value>
    </definition>

    <definition name='user_actor_area'>
      <description>linking area for user actors</description>
      <condition><var name='VIRTUAL_ADDRESS_SPACE' /></condition>
      <type name='Area' />
      <value field='virtual'><true /></value>
      <value field='private'><true /></value>
      <value field='addr'><const>0x00000000</const></value>
      <value field='size'><const>0x80000000</const></value>
    </definition>

System Control Blocks

A board-specific configuration must define two references to linking area objects where global system control blocks are allocated:

supervisor_context_area_ref specifies the area where supervisor address space global control blocks will be allocated.
user_context_area_ref specifies the area where the memory for user thread private data will be allocated.

For example, the SBC8260 board-specific configuration defines supervisor_context_area_ref as a reference to ram_area:

<definition name='supervisor_context_area_ref'>
			<description>reference to the address range where global system 
				control blocks must be allocated</description>
			<type name='Area' ref-only='yes' />
			<ref name='ram_area' />
</definition>

The mkimage tool will allocate an address range for supervisor address space control blocks in ram_area (as well as the address ranges for all segments link-edited into it).

Two configurations for user_context_area_ref are defined for the SBC8260 board.

When the micro-kernel is configured with the memory management module implementing the flat memory model (that is, when the value of the VIRTUAL_ADDRESS_SPACE configuration variable is false), user_context_area_ref is defined as a reference to ram_area:

<definition name='user_context_area_ref'>
			<description>reference to the address range where user software 
					registers must be allocated</description>
			<condition><not><var name='VIRTUAL_ADDRESS_SPACE' /></not></condition>
			<type name='Area' ref-only='yes' />
				<ref name='ram_area' />
</definition>

mkimage allocates user thread private data in ram_area.

When the micro-kernel is configured with one of memory management modules implementing the virtual memory model (that is, when the value of the VIRTUAL_ADDRESS_SPACE configuration variable is true), user_context_area_ref defines a specific address range (linking area) in the user virtual address space:

<definition name='user_context_area'>
			<description>address range where user software registers must 
				be allocated</description>
			<condition><var name='VIRTUAL_ADDRESS_SPACE' /></condition>
			<type name='Area' />
			<value field='virtual'><true /></value>
			<value field='private'><false /></value>
			<value field='addr'><const>0xeffff000</const>></value>
			<value field='size'><const>0x00001000</const></value>
</definition>

<definition name='user_context_area_ref'>
			<description>reference to the address range where user software registers 
				must be allocated</description>
			<condition><var name='VIRTUAL_ADDRESS_SPACE' /></condition>
			<type name='Area' ref-only='yes' />
			<ref name='user_context_area' />
</definition>

Kernel Address Space

A board-specific configuration can specify the initial kernel address space layout. If specified, the object that defines it must be named ksp and is usually contained in the folder named KSP. The exact semantics and requirements for the initial kernel address space specifications are family dependent.

An MPC60x family-dependent configuration must specify the initial kernel address space layout.

The SBC8260 board-dependent configuration specifies the initial kernel address space as follows:

Example 5-5 SBC8260 board-dependent configursation

  <folder name='Kernel address SPace'>
    <description>kernel address space configurations</description>

    <definition name='ksp'>
      <description>flat memory management:           system address space layout
virtual memory management:      see PPC 60x BKI</description>

      <type name='AddrSpaceMap' />
<!--
        PowerPC 60x bus SDRAM: 0x00000000 .. 0x00ffffff
-->
      <value index='size'>
        <value field='vaddr'><const>0x00000000</const></value>
        <value field='valid'><true/></value>
        <value field='paddr'><const>0x00000000</const></value>
        <value field='attr'>
          <const>KSP_PPC60x_BAT|KSP_PPC60x_M|KSP_PPC60x_RW</const>
        </value>
      </value>
<!--
        Local bus 32-bit SDRAM: 0x02000000 .. 0x02ffffff
-->
      <value index='size'>
        <value field='vaddr'><const>0x01000000</const></value>
        <value field='valid'><false/></value>
      </value>
<!--
        8260 internal memory map (IMMR): 0x0f000000 .. 0x0f01ffff
-->
      <value index='size'>
        <value field='vaddr'><const>0x0f000000</const></value>
        <value field='valid'><true/></value>
        <value field='paddr'><const>0x0f000000</const></value>
        <value field='attr'>
          <const>KSP_PPC60x_BAT|KSP_PPC60x_G|KSP_PPC60x_I|KSP_PPC60x_RW</const>
        </value>
      </value>

      <value index='size'>
        <value field='vaddr'><const>0x0f020000</const></value>
        <value field='valid'><false/></value>
      </value>
<!--
        8-bits general purpose FLASH memory: 0xe0000000 .. 0xe0ffffff
-->
<!--
        32-bits general purpose FLASH memory.
                expandable : 0xfc000000 .. 0xfcffffff
                boot       : 0xfe000000 .. 0xffffffff
-->
      <value index='size'>
        <value field='vaddr'><const>0xfc000000</const></value>
        <value field='valid'><true/></value>
        <value field='paddr'><const>0xfc000000</const></value>
        <value field='attr'>
          <const>KSP_PPC60x_BAT|KSP_PPC60x_RO</const></value>
      </value>
    </definition>

  </folder>

According to this definition, the microkernel will initially map the RAM space from physical address 0 to 0x01000000, to the virtual address 0, using one pair of BATs. It will also map the flash memory space from physical address 0xfc000000 to 0xffffffff, to the virtual address 0xfc000000 using another pair of BATs. Finally, the microkernel will map 0x00020000 bytes of 8260 Internal Memory Mapped Registers based at the physical address 0x0f000000 to the virtual address 0x0f000000. The rest of the virtual address space will be invalid.

Link-Edit Models

The link-edit models folder contains a set of link-edit models, each one describing how to link-edit a particular type of binary file.

The models.xml file contains the standard set of link-edit models:

bootconf_model specifies the default link-edit model for bootconf programs
bootstrap_model specifies the default link-edit model for bootstrap programs
debug_driver_model specifies the default link-edit model for debug agent drivers
debug_agent_model specifies the default link-edit model for debug agents
microkernel_model specifies the default link-edit model for the micro-kernel
driver_model specifies the default link-edit model for built-in drivers
supervisor_actor_model specifies the default link-edit model for supervisor actors
user_actor_model specifies the default link-edit model for user actors

Usually, the board-specific configuration includes the models defined in model.xml and defines a small number of board-specific models.

A link-edit model is specified by an object of type Binary which defines the following fields:

type is an enumeration specifying how the resulting program will be activated by the ChorusOS operating system boot process.

If a type value is not specified, the program will be activated by a specific procedure such as processor hardware reset or ChorusOS operating system afexec.
ro is an optional field specifying link-edit instructions for read-only sections (such as text and initialized read-only data). If the field is not specified, read-only sections will be link-edited using instructions for read-write sections.
rw is an optional field specifying link-edit instructions for read-write data sections. If the field is not specified, the program must not contain read-write data sections.
bss is an optional field specifying link-edit instructions for zero initialized read-write data sections. If the field is not specified, zero-initialized read-write sections will be link-edited using instructions for read-write sections.
strip is an enumeration specifying whether or not ELF headers, symbols and debug information must be included in the resulting program image.
- If the value of strip is NOTHING, the resulting image will contain all ELF headers, symbol tables and debug information.
- If the value of strip is ALL, the resulting image will contain program segment images only.
- If the value of strip is SYMBOLS, the resulting image will contain program segment images and ELF file and segment headers.

The values of the ro, rw, and bss fields are objects of the type Segment. A Segment object specifies link-edit instructions for the set of sections held by the segment and instructions for the segment loading for execution. In the Segment object:

The optional area field is a reference to an Area object. If the field is defined, each section must be link-edited into an address range dynamically allocated in the linking area, whereas if the field is not defined, each section must be link-edited at the address equal to the section's image start in the memory bank.
If the value of the boolean xip is true, the segment must be executed at its place in the memory bank. If the value of the boolean xip is false the segment image must be copied in RAM for execution.

Therefore, if for a given segment a linking area is not defined (for instance, the segment is to be link-edited at its place in the memory bank) ,the xip attribute must be true.

If, for a segment, a linking area is defined, the xip attribute can be either:

True. In this case the linking area must be a virtual one.
False. In this case the linking area can be virtual or physical.

Example 5-6 is an extract of the SBC8260 board-specific configuration file, and contains the standard link-edit models and the link-edit model definition which contains the trampoline program.

Example 5-6 SBC8260 Link-Edit Model Configuration

<folder name='Link-edit models'>
			<description>layouts of executable binary files</description>

		<folderRef href='model.xml' />  

		<folder name='Genesis2-specific link-edit models'>
			<description>layouts of executable binary files</description>

			<definition name='trampoline_model'>
				<description>trampoline (eg. power-up) program link-edit model</description>
				<type name='Binary' />
				<value field='ro'>
					<value field='xip'><true/></value>
				</value>
				<value field='strip'><const>ALL</const></value>
			</definition>
		</folder>
</folder>

The trampoline program does not contain any data and its text section must be link-edited at its place in its memory bank, trampoline_bank.

Files

The files folder contains the specification of the set of BSP files that can be included in the system image. Each file is specified by an object of the type File which contains the following fields:

path is a character string specifying the pathname of the file.
bank is a reference to the Bank object specifying the memory bank where mkimage will store the file image.
binary is an optional field specifying the link-edit model for the file. If binary is not specified, the file will be processed as a raw data file.

Example 5-7 is an extract of the SBC8260 board-specific configuration file, and contains the definitions of the File objects.

Example 5-7 SBC8260 File Configuration

  <folder name='Files'>
    <description>files that system image can potentially contain</description>

    <definition name='powerup'>
      <description>powerup initialization program</description>
      <condition>
        <equal><var name='BOOT_MODE' /><const>ROM</const></equal>
      </condition>

      <type name='File' />
      <value field='path'>
        <vstring>${BSP_DIR}/bin/sbc8260/boot/trampoline.r</vstring>
      </value>
      <value field='bank'><ref name='trampoline_bank' /></value>
      <value field='binary'><ref name='trampoline_model' /></value>
    </definition>

    <definition name='bootstrap'>
      <description>bootstrap program</description>
      <type name='File' />
      <value field='path'>
        <vstring>${BSP_DIR}/bin/sbc8260/boot/boot.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='bootstrap_model' /></value>
    </definition>

    <definition name='debug_driver'>
      <description>system debug agent driver</description>
      <type name='File' />
      <value field='path'>
        <vstring>${BSP_DIR}/bin/sbc8260/dbg/dbgBsp.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='debug_driver_model' /></value>
    </definition>

    <definition name='debug_agent'>
      <description>system debug agent</description>
      <type name='File' />
      <value field='path'>
        <vstring>${BUILD_DIR}/obj/dbg/dbgAgent.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='debug_agent_model' /></value>
    </definition>

    <definition name='microkernel'>
      <description>ChorusOS micro-kernel</description>
        <type name='File' />
      <value field='path'>
        <vstring>${BUILD_DIR}/obj/kern/kern.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='microkernel_model' /></value>
    </definition>

    <definition name='tbdec'>
      <description>built-in driver</description>
      <type name='File' />
      <value field='path'>
        <vstring>${DRV_F_DIR}/bin/drv/timer/tbDec/D_tbDec.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='driver_model' /></value>
    </definition>

    <definition name='quicc8260'>
      <description>built-in driver</description>
      <type name='File' />
      <value field='path'>
        <vstring>${DRV_F_DIR}/bin/drv/quicc/8260/D_quicc8260.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='driver_model' /></value>
    </definition>

    <definition name='fccEther'>
      <description>built-in driver</description>
      <type name='File' />
      <value field='path'>
        <vstring>${DRV_DIR}/bin/drv/net/ether/fcc/D_fccEther.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='driver_model' /></value>
    </definition>

    <definition name='sccEther'>
      <description>built-in driver</description>
      <type name='File' />
      <value field='path'>
        <vstring>${DRV_DIR}/bin/drv/net/ether/scc/D_sccEther.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='driver_model' /></value>
    </definition>

    <definition name='quiccMii'>
      <description>built-in driver</description>
      <type name='File' />
      <value field='path'>
        <vstring>${DRV_DIR}/bin/drv/mii/quiccMii/D_quiccMii.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='driver_model' /></value>
    </definition>

    <definition name='lxt970'>
      <description>built-in driver</description>
      <type name='File' />
      <value field='path'>
        <vstring>${DRV_DIR}/bin/drv/phy/lxt970/D_lxt970.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='driver_model' /></value>
    </definition>

    <definition name='sccUart'>
      <description>built-in driver</description>
      <type name='File' />
      <value field='path'>
        <vstring>${DRV_DIR}/bin/drv/uart/scc/D_sccUart.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='driver_model' /></value>
    </definition>

    <definition name='reboot'>
      <description>reboot program</description>
      <type name='File' />
      <value field='path'>
        <vstring>${BSP_DIR}/bin/sbc8260/reboot/reboot.r</vstring>
      </value>
      <value field='bank'><ref name='sys_bank' /></value>
      <value field='binary'><ref name='reboot_model' /></value>
    </definition>
  </folder>

System Image

The system image folder contains three sub-folders:

Files
Auto-generated files
Misc

Files

The files folder contains the definition of a BSP_files object, which is a list of references to File objects specifying the files that must be included in the system image.

A board-specific configuration must define a BSP_files object.

Example 5-8 is an extract of the SBC8260 board-specific configuration file, and contains the BSP_files definition.

Example 5-8 SBC8260 BSP_files Configuration

      <definition name='BSP_files'>
        <description>system image BSP files</description>
        <type name='FileList' />
        <value index='size'><ref name='debug_driver' /></value>
        <value index='size'><ref name='debug_agent' /></value>
        <value index='size'><ref name='bootstrap' /></value>
        <value index='size'><ref name='reboot' /></value>
        <value index='size'><ref name='microkernel' /></value>
        <value index='size'><ref name='tbdec' /></value>
        <value index='size'><ref name='quicc8260' /></value>
        <value index='size'><ref name='fccEther' /></value>
      </definition>

      <setting name='BSP_files'>
        <condition>
          <equal><var name='BOOT_MODE' /><const>ROM</const></equal>
        </condition>
        <value index='size'><ref name='powerup' /></value>
      </setting>

Files Generated Automatically

The mkimage tool generates three files:

The bootconf program, ${IMAGE_DIR}/bconf/${SYSTEM}_bconf.r
A program that stores the kdb symbol tables, ${IMAGE_DIR}/symb/${SYSTEM}_symb.r
A data file that stores the initial state of the system environment, ${IMAGE_DIR}/environ

The Auto-generated files folder contains definitions of File objects corresponding to these three files. The File objects must be named bootconf, symb, and env_file, respectively.

Example 5-9 is an extract of the SBC8260 board-specific configuration file, and contains the Auto-generated files definition.

Example 5-9 SBC8260 Auto-generated Files Configuration

      <folder name='Auto-generated files'>
        <description>system image files automatically \
         generated by 'mkimage' tool</description>

        <definition name='env_file'>
          <description>initial state of system environment \
           variables</description>
          <type name='File' />
          <value field='path'>
            <vstring>${IMAGE_DIR}/environ</vstring>
          </value>
          <value field='bank'><ref name='sys_bank' /></value>
        </definition>

        <definition name='symb'>
          <description>kernel debuger (kdb) symbols</description>
          <type name='File' />
          <value field='path'>
            <vstring>${IMAGE_DIR}/symb/${SYSTEM}_symb.r</vstring>
          </value>
          <value field='bank'><ref name='sys_bank' /></value>
          <value field='binary'><ref name='debug_agent_model' /></value>
        </definition>

        <definition name='bootconf'>
          <description>bootconf program</description>
          <type name='File' />
          <value field='path'>
            <vstring>${IMAGE_DIR}/bconf/${SYSTEM}_bconf.r</vstring>
          </value>
          <value field='bank'><ref name='sys_bank' /></value>
          <value field='binary'><ref name='bootconf_model' /></value>
        </definition>

      </folder>

Miscellaneous Information

The misc folder contains the following:

banks is a list of references to all Bank objects that the system image will contain.
heap_size is an integer specifying the size of the bootconf program heap.
space_barrier is an integer specifying, if required, the highest address of the supervisor address space and the lowest address of the user address space.

Example 5-10 is an extract of the SBC8260 board-specific configuration file, and contains the Misc definition.

Example 5-10 SBC8260 Misc Configuration

    <folder name='Misc'>
      <description>Misc configuration variables</description>
        
      <definition name='banks'>
        <description>list of system image banks</description>
        <type name='BankList'/>
      </definition>

      <definition name='heap_size'>
        <description>bootconf heap size</description>
        <int/>
        <const>0x00002000</const>
      </definition>

      <setting name='banks'>
        <condition>
          <equal><var name='BOOT_MODE' /><const>ROM</const></equal>
        </condition>
        <value index='size'><ref name='trampoline_bank' /></value>
      </setting>

      <setting name='banks'>
        <value index='size'><ref name='sys_bank' /></value>
      </setting>

    </folder>

Summary of Required Definitions

A board-specific configuration must define the following objects:

IMAGE_DIR
sys_bank
banks
ram_area
supervisor_context_area_ref
user_context_area_ref
BSP_files
env_file
symb
bootconf
heap_size
ksp

In addition, for x86 and MPC860 based platforms you must also define the space_barrier variable.