ChorusOS 4.0 Porting Guide

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>