<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE" xml:lang="en"><title>Boot

Table Functions</title><shortdesc>Describes how to implement the functions that the bootstrap implementation

must provide.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The <xref href="GUID-9595FD6F-1EDE-51A8-B00D-029CFDFE0F38.dita">boot table</xref> function

entries are summarised in the following table. Each is identified by its <codeph>TBootTableEntry</codeph> enumerator

that defines its position in the table. Click the enumerator symbol for more

detail on what the function must do. </p>

<table id="GUID-D7774430-469D-5E6F-8419-F23DD3E517A0">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Enumerator symbol</b>  </p> </entry>

<entry><p> <b>Summary description</b>  </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-D52E6FFC-7B8B-500C-96B3-9603EA0A3E76">BTF_WriteC</xref> </p> </entry>

<entry><p>Outputs a character to the debug port. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-1C4372C8-DFC8-5989-AC10-5A12F661AE70">BTF_RamBanks</xref> </p> </entry>

<entry><p>Gets a list of possible RAM banks. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-84D468E7-7F0E-53ED-A52F-491869900286">BTF_SetupRamBank</xref> </p> </entry>

<entry><p>Does any required setup for each RAM bank. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-52792290-48DA-5F1A-A7AD-0105A8AA37CF">BTF_RomBanks</xref> </p> </entry>

<entry><p>Gets a list of possible ROM banks. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-CE98DDA6-D809-5DEB-85A0-0332D2472CAA">BTF_SetupRomBank</xref> </p> </entry>

<entry><p>Does any required setup for each ROM bank. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-62CD8D6F-6E12-5DFC-85BC-EA24000BA588">BTF_HwBanks</xref> </p> </entry>

<entry><p>Gets a list of required I/O mappings. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-B3C6ACE9-A803-59D4-8EBD-314363905427">BTF_Reserve</xref> </p> </entry>

<entry><p>Reserves physical RAM if required. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-4DEA1D4C-EC7B-5F9A-A293-A7F80899044B">BTF_Params</xref> </p> </entry>

<entry><p>Gets a list of configuration parameters. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-EEF889E7-915F-57E9-8E2D-DC17B24C7728">BTF_Final</xref> </p> </entry>

<entry><p>Does any final setup required before booting the kernel. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-4C8986CB-0D5A-5D61-8A4B-DAC1B9D2C8B5">BTF_Alloc</xref> </p> </entry>

<entry><p>Allocates RAM during boot. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-9723F1BA-6B97-5E6A-A913-8B17C100787D">BTF_GetPdePerm</xref> </p> </entry>

<entry><p>Gets MMU PDE permissions for a mapping. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-ACAEB6E1-F8D2-51E9-AB57-4E4658E4F004">BTF_GetPtePerm</xref> </p> </entry>

<entry><p>Gets MMU PTE permissions for a mapping. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-DF0A1707-49C5-5050-B096-77704EA449DA">BTF_PTUpdate</xref> </p> </entry>

<entry><p>Called when a page table entry is updated. </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-37E8A845-6326-52F1-9607-5488B1E009A8">BTF_EnableMMU</xref> </p> </entry>

<entry><p>Enables the MMU. </p> </entry>

</row>

</tbody>

</tgroup>

</table>

<section id="GUID-D52E6FFC-7B8B-500C-96B3-9603EA0A3E76"><title>BTF_WriteC</title> <p><b>What the function should do</b> </p> <p>On non-debug bootstrap builds,

where <codeph>CFG_DebugBootRom</codeph> is set to FALSE, the function should

return immediately without doing anything. </p> <p>On debug bootstrap builds,

where <codeph>CFG_DebugBootRom</codeph> is set to TRUE, the function should

output a single character to the debug port. </p> <p>It may be necessary to

examine the <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita#GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098/GUID-FCFF2134-D89D-3861-9870-BF1B57D1241B"><apiname>TRomHeader::iDebugPort</apiname></xref> field to determine the

correct destination for the character. The function should not modify any

registers, but may change flags. </p> <p>This function can be called with

the MMU either disabled or enabled. Different I/O port addresses will normally

be required in these two cases. To simplify handling of this the following

macro is provided: </p><codeblock id="GUID-44BA5E00-45E0-5864-834A-DCC95A926F8A" xml:space="preserve">GET_ADDRESS    Rd,    PHYSICAL,    LINEAR</codeblock> <p>Where <codeph>Rd</codeph> specifies any <codeph>ARM</codeph> general purpose register. <codeph>PHYSICAL</codeph> is

the physical address of the peripheral, <codeph>LINEAR</codeph> is its linear

address. </p> <p>On the direct memory model, the <codeph>PHYSICAL</codeph> address

is always loaded into <codeph>Rd</codeph>. On the moving or multiple memory

models the macro performs a runtime check of the <codeph>CP15</codeph> control

register to determine whether the MMU is enabled. If the MMU is enabled, then

the <codeph>LINEAR</codeph> address is loaded into <codeph>Rd</codeph>, otherwise

the <codeph>PHYSICAL</codeph> address is loaded. </p> <p>Note that <codeph>CFG_DebugBootRom</codeph> is

set in the <xref href="GUID-2E4F8732-F253-5E0D-9A37-9476541E6004.dita">platform

specific configuration header file</xref>. </p> <p><b>Entry conditions</b> </p><ul>

<li id="GUID-7375F514-78DB-5620-A076-3F0D0A4E595C"><p> <codeph>R0</codeph> bottom

8 bits contain the character to be output </p> </li>

<li id="GUID-F6F936BB-2240-5C4E-AF93-9A5C63ACC28F"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-333CCEE2-F3EB-5800-8F12-AE33A9FAC225"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-D3BF3853-8542-5F0A-B3AC-4CCE02015C8A"><p> <codeph>R13</codeph> points

to a valid stack. </p> </li>

</ul> </section>

<section id="GUID-1C4372C8-DFC8-5989-AC10-5A12F661AE70"><title>BTF_RamBanks</title> <p><b>What the function should do</b> </p> <p>This function should return a

pointer to a list of RAM banks that are present. </p> <p>The list should be

a sequence of two-word entries. Each entry has the following format: </p> <fig id="GUID-3B76398A-AE4C-563B-BB52-3701983D01B4">

<image href="GUID-921AF7A3-C711-5979-877B-4B6D977888E8_d0e5006_href.png" placement="inline"/>

</fig> <p>The list is terminated by an entry that has a zero MAXSIZE. </p> <p>Of

the 32 flag bits, only one is currently defined; all undefined flags should

be zero. Flag 0, which is bit 0 of the first word is the <codeph>RAM_VERBATIM</codeph> flag

and is interpreted as follows: </p> <ul>

<li id="GUID-415A4838-2858-5EE5-B9F4-D55CDD9AE02C"><p>If clear, the specified

physical address range may or may not contain RAM, and may be only partially

occupied. In this case generic bootstrap code will probe the range to establish

if any RAM is present, and if so, which parts of the range are occupied. This

process is accompanied by calls to <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-84D468E7-7F0E-53ED-A52F-491869900286">BTF_SetupRamBank</xref>. In order for the probing algorithm to work MAXSIZE must be a power of 2

(greater than or equal to 64K), and BASE must be a multiple of MAXSIZE. </p> </li>

<li id="GUID-6CB0DED5-838E-5F58-8796-A191ED7199D4"><p>If set, the specified

physical range is known to be fully occupied by RAM, and furthermore, that

all memory controller setup for that range has already been completed. In

this case <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-84D468E7-7F0E-53ED-A52F-491869900286">BTF_SetupRamBank</xref> will

not be called for this range. </p> </li>

</ul> <p>Note that all banks declared in this list and subsequently found

to be occupied will be treated as standard RAM available for any purpose.

For this reason, internal RAM or TCRAM banks are not generally included in

the list. </p> <p><b>Entry

conditions</b> </p> <ul>

<li id="GUID-61BC32CF-36E0-598F-A97B-D3C1C032951C"><p> <codeph>R10</codeph> points

to the superpage, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-156C3C48-F4C5-5E4E-9472-C273DF805061"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-16D3C3A1-CDE2-5249-95D6-B8B37C1C2C44"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-03864AFE-0A45-551B-ADA7-6FB530F7CB4D"><p>the MMU is disabled. </p> </li>

</ul> <p><b>Exit

conditions</b> </p> <ul>

<li id="GUID-C38E1D41-7589-5368-8872-48FE33CA989A"><p> <codeph>R0</codeph> should

contain the base address of the list of banks </p> </li>

<li id="GUID-487A2C0B-DC61-5F7F-97FE-5065667134E0"><p> <codeph>R0</codeph> -<codeph>R3</codeph> and

flags may be modified, but no other registers should be modified. </p> </li>

</ul> </section>

<section id="GUID-84D468E7-7F0E-53ED-A52F-491869900286"><title>BTF_SetupRamBank</title> <p><b>What the function should do</b> </p> <p>The function should do any required

setup for each RAM bank. </p> <p>This function is called <i>twice</i> for

each RAM bank that does <i>not</i> have the <codeph>RAM_VERBATIM</codeph> flag

set (see the reference to the flag bits in the description of <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-1C4372C8-DFC8-5989-AC10-5A12F661AE70">BTF_RamBanks</xref>). </p> <p>The first call is prior to RAM bus width detection,

and the second call is after width detection. </p> <p>This function is only

required if the system has a complex and very variable RAM setup, for example

several banks of potentially different widths. Typical systems have one or

two banks of RAM of known width and all memory controller initialisation can

be done in the<xref href="GUID-F67FA7B5-F6D1-5C5C-8E10-A8E317A778E4.dita#GUID-F67FA7B5-F6D1-5C5C-8E10-A8E317A778E4/GUID-C111DA06-F7EE-5E70-8D86-26BA2213B506">InitialiseHardware()</xref> function;

in this case this function can simply return without performing any operation. </p> <p><b>Entry conditions</b> </p> <ul>

<li id="GUID-4080EA07-03AE-5D7C-9931-71DC7A7844D6"><p> <codeph>R1</codeph> holds

the physical base address of a bank </p> </li>

<li id="GUID-02D174D3-A176-55A1-81C6-BEDBA72023FC"><p> <codeph> R3 = 0xFFFFFFFF</codeph> for

the first call</p> <p> <codeph> R3 = 0x0000000Y</codeph> for the second call,

where the bottom 4 bits represent the validity of each of the 4 byte lanes

(bit 0=1 if D0-7 are valid, bit 1=1 if D8-15 are valid, etc.) </p> </li>

<li id="GUID-0DD72D2D-D26D-59B1-B60B-5DA41D8B4FF0"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-7EF8D070-7843-5164-BEC5-E6EC7A2B4159"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-86030AEF-E1C5-5CCA-8E95-C9A360286609"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-88F1940A-A7A2-5340-8278-BB2CC269B3DE"><p>the MMU is disabled. </p> </li>

</ul> <p><b>Exit

conditions</b> </p> <p>Other than flags, no registers should be modified. </p> </section>

<section id="GUID-52792290-48DA-5F1A-A7AD-0105A8AA37CF"><title>BTF_RomBanks</title> <p><b>What the function should do</b> </p> <p>This function should return a

pointer to a list of XIP ROM banks that are present. It is not called if the

bootstrap is found to be running in RAM; in this case it is assumed that all

XIP code is in RAM. </p> <p>The list should be a sequence of four-word entries.

Each entry has the following format: </p> <fig id="GUID-35A65482-24F6-5F9A-83B8-ED490F651A9A">

<image href="GUID-4E6520E8-4BF1-55D1-B643-81B8D2816D1D_d0e5246_href.png" placement="inline"/>

</fig> <p>The list is terminated by a zero value four-word entry. </p> <p>Only

the first, second and fourth words of each entry are actually used by the

rest of the bootstrap. The third is there mainly to support autodetection

schemes. </p> <p>The <xref href="GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C.dita#GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C/GUID-7361BC74-7164-52EE-9A5B-D254560D1939">ROM_BANK</xref> macro

can be used to declare ROM bank entries. </p> <p><b>Entry conditions</b> </p> <ul>

<li id="GUID-ABFD5EA9-459A-5961-9181-FC5A15463AE7"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-888C592D-F49A-508B-80EF-E729D33C1FAE"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-CC543EA9-34B7-5806-B987-6565CD07B052"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-618F3F1A-E91B-55AA-80D5-D2E894720AB9"><p>the MMU is disabled. </p> </li>

</ul> <p><b>Exit

conditions</b> </p> <ul>

<li id="GUID-DAC651F9-6EF3-584D-92D2-388E7EC8A13B"><p> <codeph>R0</codeph> should

contain the base address of the list of ROM banks. </p> </li>

<li id="GUID-F8A205C2-4605-512A-A721-B6D2506D7263"><p> <codeph>R0</codeph> -<codeph>R3</codeph> and

flags may be modified, but no other registers should be modified. </p> </li>

</ul> </section>

<section id="GUID-CE98DDA6-D809-5DEB-85A0-0332D2472CAA"><title>BTF_SetupRomBank</title> <p><b>What the function should do</b> </p> <p>The function should do any required

setup for each ROM bank. </p> <p>It is called once immediately after the call

to <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-52792290-48DA-5F1A-A7AD-0105A8AA37CF">BTF_RomBanks</xref> and

then it is subsequently called again for <i>each</i> ROM bank in the list

returned by <codeph>BTF_RomBanks</codeph>. It is not called if the bootstrap

is running in RAM. </p> <p>This function is intended to support autodetection

of the system ROM configuration. For example, the first call with <codeph>R11</codeph> set

to zero could be used to set the bus controller to 32 bit width to enable

width detection to be performed on ROM banks other than the boot block. Subsequent

per-bank calls could determine the width (possibly using an algorithm that

repeatedly reads from the same address and checks which bits are consistent)

and the size of the ROM bank. These would be written to the entry pointed

by <codeph>R11</codeph> and the bus controller set up correctly for that ROM

bank. If the bank is absent, then the size in the structure pointed to by <codeph>R11</codeph> is

set to zero to remove it from the list. </p> <p><b>Entry conditions</b> </p> <ul>

<li id="GUID-A13AC2C7-01EC-5A15-92F3-1ABF1FB03DD2"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-CB332F6C-1B59-5B77-8396-060C9EE413E3"><p>On the first call: </p> <ul>

<li id="GUID-96520453-4106-55AF-A0F2-D3533594EEE9"><p> <codeph>R11</codeph> contains

0 </p> </li>

<li id="GUID-025A5A35-6A7E-5F84-8B05-39E6427D0F63"><p> <codeph>R0</codeph> contains

the base address of the list of ROM banks returned by <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-52792290-48DA-5F1A-A7AD-0105A8AA37CF">BTF_RomBanks</xref> </p> </li>

</ul> <p>On subsequent calls: </p> <ul>

<li id="GUID-CFAED6F6-4344-505B-920E-14B99784621A"><p> <codeph>R11</codeph> points

to a RAM copy of the entry corresponding to the ROM bank currently being processed </p> </li>

</ul> </li>

<li id="GUID-4456CB76-38BA-568B-9295-C965B7B70069"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-0087F2C0-343C-5F81-AC75-DEEE357A8B54"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-37648CD7-CB3D-547F-BC81-B354F64CF827"><p>the MMU is disabled. </p> </li>

</ul> <p><b>Exit

conditions</b> </p> <p>For calls where <codeph>R11</codeph> is non-zero, the

entry pointed to by <codeph>R11</codeph> may be modified by this function

call. </p> <p>If the entry size for a bank is set to zero, then that bank

is assumed not to exist, and is removed from the list of ROM banks. </p> <p>Registers <codeph>R0</codeph> -<codeph>R4</codeph> and

flags may be modified by this function; all other registers should be preserved. </p> </section>

<section id="GUID-62CD8D6F-6E12-5DFC-85BC-EA24000BA588"><title>BTF_HwBanks</title> <p><b>What the function should do</b> </p> <p>This function should return a

pointer to a list of required I/O mappings. </p> <p>The list should be a sequence

of one-word and two-word entries, terminated by a zero-filled word. The entries

in the list are defined using the <xref href="GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C.dita#GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C/GUID-7728C7F2-BB04-518B-8B0A-752CB799A561">macros

for declaring I/O mappings</xref>: <codeph>HW_MAPPING</codeph>, <codeph>HW_MAPPING_EXT</codeph>, <codeph>HW_MAPPING_EXT2</codeph>,

and <codeph>HW_MAPPING_EXT3</codeph>. </p> <p>In the template port, this is

implemented in <filepath>os/kernelhwsrv/bsptemplate/asspandvariant/template_variant/bootstrap/template.s</filepath>.

Find the symbol <codeph>GetHwBanks</codeph>: </p> <codeblock id="GUID-93B8920C-C244-5CEE-95B4-1F49BB1D8B19" xml:space="preserve">GetHwBanks    ROUT

        ADR        r0, %FT1

        MOV        pc, lr

        ...

        DCD            0                                            ; terminator

</codeblock> <p>The pointer in the boot table to this list of I/O mappings

is defined by the symbol <codeph>GetHwBanks</codeph>. </p> <codeblock id="GUID-AAC33135-33B2-5B31-8D3B-906636669310" xml:space="preserve">BootTable

    ...

    DCD    GetHwBanks                ; get list of HW banks

    ...</codeblock> <p>To support Level 2 cache (either L210 or L220), you

need to add the base address of the Level 2 cache controller to the list of

hardware banks. For example: </p> <codeblock id="GUID-F28CD3A1-CBB8-5052-ADC1-96A23FE9DA5D" xml:space="preserve">GetHwBanks  ROUT

        ADR     r0, %FT1

        MOV     pc, lr

        ...

        HW_MAPPING  L210CtrlBasePhys, 1, HW_MULT_1M

        ...

        DCD     0                                 ; terminator

</codeblock> <p>See also the<xref href="GUID-F67FA7B5-F6D1-5C5C-8E10-A8E317A778E4.dita#GUID-F67FA7B5-F6D1-5C5C-8E10-A8E317A778E4/GUID-C111DA06-F7EE-5E70-8D86-26BA2213B506">InitialiseHardware()</xref> function. </p> <p><b>Entry

conditions</b> </p> <ul>

<li id="GUID-74CDF102-52AD-5BE2-83BB-4486D5DCF904"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-E6B28758-C709-51E9-9604-12EF39EF95EA"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-BCA82596-751E-5045-BADA-E71659254555"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-5F7B169A-F4C4-587F-AD33-46CF05619113"><p>the MMU is disabled. </p> </li>

</ul> <p><b>Exit

conditions</b> </p> <ul>

<li id="GUID-59BB29EB-3437-5E3A-ADC8-6AA57BD10DFA"><p> <codeph>R0</codeph> should

contain the base address of the list of banks </p> </li>

<li id="GUID-0CEEEA0C-58CB-5A4E-9D94-EFE0496F264F"><p> <codeph>R0</codeph> -<codeph>R3</codeph> and

flags may be modified, but no other registers should be modified. </p> </li>

</ul> </section>

<section id="GUID-B3C6ACE9-A803-59D4-8EBD-314363905427"><title>BTF_Reserve</title> <p><b>What the function should do</b> </p> <p>The function reserves physical

RAM if required. </p> <p>It is called before the bootstrap's memory allocator

(<xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-4C8986CB-0D5A-5D61-8A4B-DAC1B9D2C8B5">BTF_Alloc</xref>)

is initialised to allow physical RAM to be reserved for any platform specific

purpose. </p> <p>There are two methods available for reserving physical RAM: </p> <ol id="GUID-A68E974D-B79F-5EFF-AC43-FC068B2A0B8C">

<li id="GUID-37C98A1E-AD3A-5D36-BA64-B24E3EC5045A"><p>Use the generic bootstrap

function <codeph>ExciseRamArea()</codeph>, implemented in <filepath>os/kernelhwsrv/kernel/eka/kernel/arm/bootutils.s</filepath>.

This removes a specified region from the list of RAM blocks present in the

system. Subsequently, the excised area will no longer be treated as RAM. If

this method is used, then the excised areas must be a multiple of 64K in size

and aligned to a 64K boundary. </p> <p>The following entry conditions apply

when calling <codeph>ExciseRamArea()</codeph>: </p> <ul>

<li id="GUID-8B81140B-36A5-5DE2-A04A-59D6889935B3"><p> <codeph>R0</codeph> =

physical base address of the area to be excised </p> </li>

<li id="GUID-56DCD069-6683-5585-9DB5-04F540409F18"><p> <codeph>R1</codeph> =

size of area to be excised </p> </li>

<li id="GUID-17C76EFB-E6C3-5645-9E92-4CBC9237EA60"><p> <codeph>R9</codeph> = <codeph>SSuperPageBase::iRamBootData</codeph>  </p> </li>

<li id="GUID-24675744-4FD7-59BE-993A-0A939682C910"><p> <codeph> R10</codeph> points

to the super page </p> </li>

<li id="GUID-39FF3824-78CF-5B83-904A-270E1CC5686B"><p> <codeph> R11</codeph> =

0 </p> </li>

<li id="GUID-2DF3FCAF-BEFC-5A87-AD8C-D38DD2A8DFA3"><p> <codeph> R13</codeph> points

to a valid stack. </p> </li>

</ul> </li>

<li id="GUID-C99A07B3-BF0A-58CF-9CA1-37891380D7C5"><p>Write a list of reserved

RAM blocks to the address passed in R11. The list should consist of two-word

entries, the first word being the physical base address of the block and the

second word the size. The list is terminated by an entry with zero size. The

listed blocks will still be recognised as RAM by the kernel but will be marked

as allocated during kernel boot. The blocks in the list should be multiples

of 4K in size and aligned to a 4K boundary. </p> </li>

</ol> <p>If both methods are used simultaneously, then the <codeph>ExciseRamArea()</codeph> function

will require recalculation of the value in R11 for the second method. The

correct value can be found by loading <codeph>R11</codeph> first with <codeph>SSuperPageBase::iRamBootData</codeph>,

stepping forward 8 bytes at a time until an entry with a zero-filled second

word is found, and then stepping on by a further 8 bytes. </p> <p><b>Entry conditions</b> </p> <ul>

<li id="GUID-701D97D3-629C-5270-9E98-5677B52F12E9"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-43402496-5018-5473-859A-3B2C5289FE3B"><p> <codeph>r11</codeph> points

to the place where the pre-allocated block list should be written </p> </li>

<li id="GUID-E25602F8-36F8-5C49-B3A8-D2B37DD7DEB7"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-E53BCEBB-AB2A-52C5-B3C8-FDFC777EB35C"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-61ED18DA-CB5B-50F1-81F1-59C8EEC68E15"><p>the MMU is disabled. </p> </li>

</ul> <p><b>Exit

conditions</b> </p> <p>The function can modify <codeph>R0</codeph>, <codeph>R1</codeph>, <codeph>R2</codeph>,<codeph>R3</codeph>, <codeph>R11</codeph> and the flags, but should preserve all other registers. </p> </section>

<section id="GUID-4DEA1D4C-EC7B-5F9A-A293-A7F80899044B"><title>BTF_Params</title> <p><b>What the function should do</b> </p> <p>The function should return the

value of a run-time configurable boot parameter. The parameter is identified

by one of the values of the <codeph>TBootParam</codeph> enumeration, which

is passed in <codeph>R0</codeph>. </p> <p>Typically, the function is implemented

as follows: </p> <codeblock id="GUID-60C84CAA-3B19-5FC1-8192-05519C3E76DD" xml:space="preserve">GetParameters ROUT

    ADR    r1, ParameterTable

    B    FindParameter

ParameterTable    ; Include any parameters specified in TBootParam

                ; enum here if you want to override them.

    DCD    BPR_x, value    ; parameter number, parameter value

    DCD    -1                ; terminator

</codeblock> <p>This implementation calls the generic function <codeph>FindParameter()</codeph>,

which performs the necessary lookup of the parameter number in the table.

The parameter table should consist of a list of two-word entries, the first

word being the parameter number and the second the parameter value. The list

should be terminated by a negative parameter number. The generic function

searches this table for the parameter value, and if found, returns it in <codeph>R0</codeph> as

stated in <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-1981A220-876C-5BBD-A84C-E895F133B6B9">Exit

conditions</xref>. </p> <p>Note that the address of this parameter table is

also passed to the <codeph>InitCpu()</codeph> function by the <xref href="GUID-F67FA7B5-F6D1-5C5C-8E10-A8E317A778E4.dita#GUID-F67FA7B5-F6D1-5C5C-8E10-A8E317A778E4/GUID-C111DA06-F7EE-5E70-8D86-26BA2213B506">InitialiseHardware()</xref> public function. </p> <p>Each entry in the boot

parameter table is identified by a <codeph>TBootParam</codeph> enumeration

value that defines its position within that table. The entries have the following

meaning: </p> <table id="GUID-B0C82F23-2342-53FE-8CFE-E82DA628D6B5">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Enumerator symbol</b>  </p> </entry>

<entry><p> <b>Summary description</b>  </p> </entry>

</row>

<row>

<entry><p> <codeph> BPR_InitialMMUCRClear</codeph>  </p> </entry>

<entry><p>Mask of bits to clear in MMUCR in the <codeph>InitCpu()</codeph> generic

function. Defaults to 0xFFFFFFFF, i.e. clear all bits. </p> </entry>

</row>

<row>

<entry><p> <codeph> BPR_InitialMMUCRSet</codeph>  </p> </entry>

<entry><p>Mask of bits to set in MMUCR in the <codeph>InitCpu()</codeph> generic

function after clearing those specified by <codeph>BPR_InitialMMUCRClear</codeph>.

Defaults to a CPU-dependent value. </p> </entry>

</row>

<row>

<entry><p> <codeph>BPR_FinalMMUCRClear</codeph>  </p> </entry>

<entry><p>Mask of bits to clear in MMUCR when the MMU is enabled. Defaults

to 0, which means do not clear any bits. </p> </entry>

</row>

<row>

<entry><p> <codeph>BPR_FinalMMUCRSet</codeph>  </p> </entry>

<entry><p>Mask of bits to set in MMUCR when the MMU is enabled after clearing

those specified in <codeph>BPR_FinalMMUCRSet</codeph>. Defaults to a CPU-dependent

value. </p> </entry>

</row>

<row>

<entry><p> <codeph>BPR_AuxCRClear</codeph>  </p> </entry>

<entry><p>Mask of bits to clear in AUXCR in the <codeph>InitCpu()</codeph> Symbian

platform generic function. Defaults to a CPU dependent value. </p> </entry>

</row>

<row>

<entry><p> <codeph>BPR_AuxCRSet</codeph>  </p> </entry>

<entry><p>Mask of bits to set in AUXCR in the <codeph>InitCpu()</codeph> Symbian

platform generic function after clearing those specified by <codeph>BPR_InitialAUXCRClear</codeph>.

Defaults to a CPU-dependent value. </p> </entry>

</row>

<row>

<entry><p> <codeph>BPR_CAR</codeph>  </p> </entry>

<entry><p>Initial value to set for coprocessor access register if present.

Defaults to 0. </p> </entry>

</row>

<row>

<entry><p> <codeph>BPR_UncachedLin</codeph>  </p> </entry>

<entry><p>Mandatory parameter on the direct memory model, not used on other

memory models. The value is copied into <codeph>SSuperPageBase::iUncachedAddress</codeph> for

use by any code which needs to do an uncached memory access, usually for memory

controller synchronisation purposes. On systems with an MMU, this address

will be mapped as an alias of the super page and must refer to the base address

of a 1Mb region of unused virtual address space, aligned on a 1Mb boundary.

On a system with no MMU, this address should be the physical address of some

uncached memory. </p> </entry>

</row>

<row>

<entry><p> <codeph> BPR_PageTableSpace</codeph>  </p> </entry>

<entry><p>Used only on the direct memory model on systems with an MMU. Specifies

the amount of RAM to reserve for page tables. Defaults to 32K. </p> </entry>

</row>

<row>

<entry><p> <codeph>BPR_KernDataOffset</codeph>  </p> </entry>

<entry><p>Used only on the direct memory model. Specifies the offset from

the base of the super page to the base of the kernel .data section. Defaults

to 8K. </p> </entry>

</row>

<row>

<entry><p> <codeph> BPR_BootLdrImgAddr </codeph>  </p> </entry>

<entry><p>Mandatory parameter for bootloader configurations; not required

for other configurations. Specifies the physical base address of the RAM-loaded

image. </p> </entry>

</row>

<row>

<entry><p> <codeph>BPR_BootLdrExtraRAM</codeph>  </p> </entry>

<entry><p>Only used on bootloader configurations. Specifies the amount of

'user' memory to reserve (this is in fact used to satisfy <codeph>Epoc::AllocPhysicalRam</codeph> requests,

usually for video RAM) in the case where the RAM-loaded image is at the bottom

of RAM and so the bootloader RAM is at the top. Defaults to 1MB. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Entry

conditions</b> </p> <ul>

<li id="GUID-38ED47F2-BD04-5039-8A71-81D787C6B679"><p>R0 contains the number

identifying the required parameter; see the <codeph>TBootParam</codeph> enumerator

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/arm/bootdefs.h</filepath>. </p> </li>

<li id="GUID-151A442C-5903-50F5-B425-0FB80CE950B8"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-916DB071-2433-512B-A4C4-70C736DABE15"><p> <codeph>r11</codeph> points

to the place where the pre-allocated block list should be written </p> </li>

<li id="GUID-32D51889-00F9-5968-A3BC-A1752825B8AC"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-7F5685B5-95EA-5C03-9E92-B50B60DAA2FC"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-E5D06E47-BF01-51D1-BC15-AF5D588AB5A5"><p>the MMU is disabled. </p> </li>

</ul> <p id="GUID-1981A220-876C-5BBD-A84C-E895F133B6B9"><b>Exit conditions</b> </p> <p>If

the parameter value is specified, it should be returned in <codeph>R0</codeph> and

the <codeph>N</codeph> flag should be cleared. </p> <p>If the parameter value

is not specified, the <codeph>N</codeph> flag should be set. </p> <p>Registers <codeph>R0</codeph> , <codeph>R1</codeph>, <codeph>R2</codeph> and

the flags may be modified. All other registers should be preserved. </p> </section>

<section id="GUID-EEF889E7-915F-57E9-8E2D-DC17B24C7728"><title>BTF_Final</title> <p><b>What the function should do</b> </p> <p>The function should do any final

setup required before booting the kernel. It is called at the end of the bootstrap,

just before booting the kernel. </p> <p>The function should: </p> <ul>

<li id="GUID-388B647D-5AD6-58FD-B78A-67DBC6B945A5"><p>Map any cache flushing

areas required by the CPU. </p> <p>Processors that flush the data cache by

reading dummy addresses or by allocating dummy addresses into the cache (e.g.

StrongARM and XScale processors) will need a main cache flush area. If the

processor has an alternate data cache (e.g. StrongARM and XScale mini data

cache) a second flush area may be required for it. On the moving and multiple

memory models the linear addresses used for these flushing areas are fixed

(<codeph>KDCacheFlushArea</codeph> and <codeph>KDCacheFlushArea</codeph> +1MB

respectively). On the direct memory model any unused linear address may be

selected. The linear addresses used should be written into <codeph>SSuperPageBase::iDCacheFlushArea</codeph> and <codeph>SSuperPageBase::iAltDCacheFlushArea</codeph>. In addition, the fields <codeph>SSuperPageBase::iDCacheFlushWrap</codeph> and <codeph>SSuperPageBase::iAltDCacheFlushWrap</codeph> should

be written with a power of 2 at least twice the cache size and no bigger than

half the reserved address area. A value of 0x00080000 (512KB) is usually used. </p> </li>

<li id="GUID-B0061BBC-DEBE-5A12-B11B-39F73FFC7072"><p>Populate any super page

or CPU page fields with platform-specific information used by the variant,

for example addresses of CPU idle routines in the bootstrap. Routines can

be placed in the bootstrap if known alignment is required for the routine. </p> </li>

</ul> <p><b>Entry

conditions</b> </p> <ul>

<li id="GUID-61AA6724-B809-5742-A6FD-F39D5269B2EE"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath>  </p> </li>

<li id="GUID-B58A49E2-B4AA-53D4-816A-B48491A707D8"><p> <codeph>r11</codeph> points

to the kernel image header, a <xref href="GUID-88C84EC0-B63E-3848-82BF-E3A81E2F7E9A.dita"><apiname>TRomImageHeader</apiname></xref> object </p> </li>

<li id="GUID-34A71E2F-9232-5DAF-AF04-D51822B65E8D"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-38C918F2-9769-55EC-A9F1-5D64CCB6EA2B"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-538DE8FF-2BE4-5D50-933C-F6D7E94A3CC1"><p>the MMU is disabled. </p> </li>

</ul> <p><b>Exit

conditions</b> </p> <p>Registers <codeph>R0</codeph> to <codeph>R9</codeph> and

flags may be modified; other registers should be preserved. </p> </section>

<section id="GUID-4C8986CB-0D5A-5D61-8A4B-DAC1B9D2C8B5"><title>BTF_Alloc</title> <p><b>What the function should do</b> </p> <p>Allocates RAM during boot. </p> <p>This

function is called at various points to initialise the memory allocator, or

to allocate physical RAM. A generic implementation is provided for this function

and this will normally be sufficient, so a typical implementation for this

function reduces to: </p> <codeblock id="GUID-90A5743F-4FB5-59A4-9FC8-DAB2CCDF8EB0" xml:space="preserve">DCD HandleAllocRequest</codeblock> <p>in

the boot table. For systems with no MMU, the function name should be changed

to <codeph>AllocatorStub</codeph>. </p> <p>It is advisable not to override

this function. </p> <p><b>Entry

conditions</b> </p> <ul>

<li id="GUID-72DBAE17-60F1-5EF1-B9B1-2E69E109FE3B"><p>R2 contains the type

of allocation required; this is defined by one of the values of the <codeph>TBootMemAlloc</codeph> enumeration </p> </li>

<li id="GUID-70690B58-7B7B-51CE-A678-F25222CC6664"><p>R4 contains the size

to allocate (as a log to base 2) for allocations of type <codeph>BMA_Kernel</codeph> </p> </li>

<li id="GUID-C993DE47-01D2-5D7F-98FE-5CAEDAF16079"><p> <codeph>R10</codeph> points

to the super page, represented by the <codeph>SSuperPageBase</codeph> struct

defined in <filepath>os\kernelhwsrv\kernel\eka\include\kernel\kernboot.h</filepath>  </p> </li>

<li id="GUID-030F04FA-1919-5643-A634-60E9A9228FA9"><p> <codeph>R12</codeph> points

to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li>

<li id="GUID-DB3E70CC-7B35-5952-BE93-5A47674F3A5A"><p> <codeph>R13</codeph> points

to a valid stack </p> </li>

<li id="GUID-7D7962A8-57A0-5F16-9651-0A0E71F1605C"><p>the MMU may be enabled

or disabled. </p> </li>

</ul> <p>The type of allocation required is defined by the value of the enumerator <codeph>TBootMemAlloc</codeph>,

defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/arm/bootdefs.h</filepath>.

The allocation types are as follows: </p> <table id="GUID-756C039B-D079-5EFC-B3A6-37675FD4CCBC">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p> <b>Enumerator symbol</b>  </p> </entry>

<entry><p> <b>Summary description</b>  </p> </entry>

</row>

<row>

<entry><p> <codeph>BMA_Init</codeph>  </p> </entry>

<entry><p>Called to initialise the memory allocator. </p> </entry>

</row>

<row>

<entry><p> <codeph>BMA_SuperCPU </codeph>  </p> </entry>

<entry><p>Should return the physical address of the super page in R0. </p> </entry>