--- a/Symbian3/PDK/Source/GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita	Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita	Thu Mar 11 18:02:22 2010 +0000
@@ -1,597 +1,597 @@
-<?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_d0e259514_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_d0e259754_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
-OS 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
-OS 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>
-</row>
-<row>
-<entry><p> <codeph>BMA_PageDirectory</codeph>  </p> </entry>
-<entry><p>Should return the physical address of the page directory in R0. </p> </entry>
-</row>
-<row>
-<entry><p> <codeph>BMA_PageTable</codeph>  </p> </entry>
-<entry><p>Allocate a new page table (1KB size and 1KB alignment) and return
-its physical address in R0. It is not necessary to clear the page table here. </p> </entry>
-</row>
-<row>
-<entry><p> <codeph>BMA_Kernel</codeph>  </p> </entry>
-<entry><p>Allocate a page of size 2R4. This must be a valid processor page
-size; on ARM this means R4=12, 16 or 20. The returned physical address will
-be a multiple of 2R4. If no page of the requested size can be allocated a
-page of the largest possible smaller size will be allocated and R4 will be
-modified accordingly.<note>If no page of any size can be allocated this call
-will fault the system.</note> </p> </entry>
-</row>
-<row>
-<entry><p> <codeph>BMA_Reloc</codeph>  </p> </entry>
-<entry><p>Called when the allocator data structures need to be relocated in
-memory. On entry R0 contains the offset to apply to all pointers (that is,
-the new address of data minus the old address). It is assumed that all the
-allocator data is contained in the super page or CPU page and that there are
-no pointers to areas which could be relocated independently. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p><b>Exit
-conditions</b> </p> <p> <codeph>R0</codeph> and flags may be modified. For <codeph>BMA_Kernel</codeph> allocations, <codeph>R4</codeph> may
-also be modified. All other registers should be preserved. </p> </section>
-<section id="GUID-9723F1BA-6B97-5E6A-A913-8B17C100787D"><title>BTF_GetPdePerm</title> <p><b>What the function should do</b> </p> <p>This function is called at various
-points to translate a standardised permission descriptor along with the size
-of mapping required to the PDE permission/attribute bits needed for such a
-mapping. A standardised permission descriptor can be either an index into
-the boot table (for any of the standard permission types) or the value generated
-by a <xref href="GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C.dita#GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C/GUID-B5EC22B5-B995-5D54-8F33-1B6FCE11BB3F">BTP_ENTRY</xref> macro. </p> <p>A
-generic implementation is provided for this function and it should not be
-necessary to override it. A typical implementation for this function then
-just reduces to: </p> <codeblock id="GUID-57B1277B-B322-506B-A5EC-A4D10C5FA420" xml:space="preserve">DCD GetPdeValue</codeblock> <p>in
-the boot table. </p> <p>Note that for systems with no MMU, this function is
-not required. </p> </section>
-<section id="GUID-ACAEB6E1-F8D2-51E9-AB57-4E4658E4F004"><title>BTF_GetPtePerm</title> <p><b>What the function should do</b> </p> <p>This function is called at various
-points to translate a standardised permission descriptor along with the size
-of mapping required to the PTE permission/attribute bits needed for such a
-mapping. A standardised permission descriptor can be either an index into
-the boot table (for any of the standard permission types) or the value generated
-by <xref href="GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C.dita#GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C/GUID-B5EC22B5-B995-5D54-8F33-1B6FCE11BB3F">BTP_ENTRY</xref> macro. </p> <p>A
-generic implementation is provided for this function and it should not be
-necessary to override it. In the boot table, a typical implementation for
-this function then reduces to: </p> <codeblock id="GUID-E0836362-3BAE-54CB-9A1E-C81C1E823550" xml:space="preserve">DCD GetPteValue</codeblock> <p>Note
-that for systems with no MMU, this function is not required. </p> </section>
-<section id="GUID-DF0A1707-49C5-5050-B096-77704EA449DA"><title>BTF_PTUpdate</title> <p><b>What the function should do</b> </p> <p>This function is called whenever
-a PDE or PTE is updated. It performs whatever actions are required to make
-sure that the update takes effect. This usually means draining the write buffer
-and flushing the TLB (both TLBs on a Harvard architecture system). </p> <p>A
-generic implementation is provided for this function and it should not be
-necessary to override it. In the boot table, a typical implementation for
-this function then reduces to: </p> <codeblock id="GUID-FE889B79-013E-5A93-8ED0-51BEB97623A4" xml:space="preserve">DCD PageTableUpdate</codeblock> <p>Note
-that for systems with no MMU, this function is not required. </p> </section>
-<section id="GUID-37E8A845-6326-52F1-9607-5488B1E009A8"><title>BTF_EnableMMU</title> <p><b>What the function should do</b> </p> <p>This function is called to enable
-the MMU and thereby switch from operating with physical addresses to operating
-with virtual addresses. </p> <p>A generic implementation is provided for this
-function and it should not be necessary to override it. In the boot table,
-a typical implementation for this function then reduces to: </p> <codeblock id="GUID-4FB9161D-18BA-5ADC-AB32-4D8E86DAF55F" xml:space="preserve">DCD EnableMmu</codeblock> <p>Note
-that for systems with no MMU, this function is not required. </p> </section>
+<?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_d0e259514_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_d0e259754_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
+OS 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
+OS 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>
+</row>
+<row>
+<entry><p> <codeph>BMA_PageDirectory</codeph>  </p> </entry>
+<entry><p>Should return the physical address of the page directory in R0. </p> </entry>
+</row>
+<row>
+<entry><p> <codeph>BMA_PageTable</codeph>  </p> </entry>
+<entry><p>Allocate a new page table (1KB size and 1KB alignment) and return
+its physical address in R0. It is not necessary to clear the page table here. </p> </entry>
+</row>
+<row>
+<entry><p> <codeph>BMA_Kernel</codeph>  </p> </entry>
+<entry><p>Allocate a page of size 2R4. This must be a valid processor page
+size; on ARM this means R4=12, 16 or 20. The returned physical address will
+be a multiple of 2R4. If no page of the requested size can be allocated a
+page of the largest possible smaller size will be allocated and R4 will be
+modified accordingly.<note>If no page of any size can be allocated this call
+will fault the system.</note> </p> </entry>
+</row>
+<row>
+<entry><p> <codeph>BMA_Reloc</codeph>  </p> </entry>
+<entry><p>Called when the allocator data structures need to be relocated in
+memory. On entry R0 contains the offset to apply to all pointers (that is,
+the new address of data minus the old address). It is assumed that all the
+allocator data is contained in the super page or CPU page and that there are
+no pointers to areas which could be relocated independently. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p><b>Exit
+conditions</b> </p> <p> <codeph>R0</codeph> and flags may be modified. For <codeph>BMA_Kernel</codeph> allocations, <codeph>R4</codeph> may
+also be modified. All other registers should be preserved. </p> </section>
+<section id="GUID-9723F1BA-6B97-5E6A-A913-8B17C100787D"><title>BTF_GetPdePerm</title> <p><b>What the function should do</b> </p> <p>This function is called at various
+points to translate a standardised permission descriptor along with the size
+of mapping required to the PDE permission/attribute bits needed for such a
+mapping. A standardised permission descriptor can be either an index into
+the boot table (for any of the standard permission types) or the value generated
+by a <xref href="GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C.dita#GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C/GUID-B5EC22B5-B995-5D54-8F33-1B6FCE11BB3F">BTP_ENTRY</xref> macro. </p> <p>A
+generic implementation is provided for this function and it should not be
+necessary to override it. A typical implementation for this function then
+just reduces to: </p> <codeblock id="GUID-57B1277B-B322-506B-A5EC-A4D10C5FA420" xml:space="preserve">DCD GetPdeValue</codeblock> <p>in
+the boot table. </p> <p>Note that for systems with no MMU, this function is
+not required. </p> </section>
+<section id="GUID-ACAEB6E1-F8D2-51E9-AB57-4E4658E4F004"><title>BTF_GetPtePerm</title> <p><b>What the function should do</b> </p> <p>This function is called at various
+points to translate a standardised permission descriptor along with the size
+of mapping required to the PTE permission/attribute bits needed for such a
+mapping. A standardised permission descriptor can be either an index into
+the boot table (for any of the standard permission types) or the value generated
+by <xref href="GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C.dita#GUID-25941CD2-D124-55DD-8716-ACC93E3F1D6C/GUID-B5EC22B5-B995-5D54-8F33-1B6FCE11BB3F">BTP_ENTRY</xref> macro. </p> <p>A
+generic implementation is provided for this function and it should not be
+necessary to override it. In the boot table, a typical implementation for
+this function then reduces to: </p> <codeblock id="GUID-E0836362-3BAE-54CB-9A1E-C81C1E823550" xml:space="preserve">DCD GetPteValue</codeblock> <p>Note
+that for systems with no MMU, this function is not required. </p> </section>
+<section id="GUID-DF0A1707-49C5-5050-B096-77704EA449DA"><title>BTF_PTUpdate</title> <p><b>What the function should do</b> </p> <p>This function is called whenever
+a PDE or PTE is updated. It performs whatever actions are required to make
+sure that the update takes effect. This usually means draining the write buffer
+and flushing the TLB (both TLBs on a Harvard architecture system). </p> <p>A
+generic implementation is provided for this function and it should not be
+necessary to override it. In the boot table, a typical implementation for
+this function then reduces to: </p> <codeblock id="GUID-FE889B79-013E-5A93-8ED0-51BEB97623A4" xml:space="preserve">DCD PageTableUpdate</codeblock> <p>Note
+that for systems with no MMU, this function is not required. </p> </section>
+<section id="GUID-37E8A845-6326-52F1-9607-5488B1E009A8"><title>BTF_EnableMMU</title> <p><b>What the function should do</b> </p> <p>This function is called to enable
+the MMU and thereby switch from operating with physical addresses to operating
+with virtual addresses. </p> <p>A generic implementation is provided for this
+function and it should not be necessary to override it. In the boot table,
+a typical implementation for this function then reduces to: </p> <codeblock id="GUID-4FB9161D-18BA-5ADC-AB32-4D8E86DAF55F" xml:space="preserve">DCD EnableMmu</codeblock> <p>Note
+that for systems with no MMU, this function is not required. </p> </section>
 </conbody></concept>
\ No newline at end of file