|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE" xml:lang="en"><title>Boot |
|
13 Table Functions</title><shortdesc>Describes how to implement the functions that the bootstrap implementation |
|
14 must provide.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>The <xref href="GUID-9595FD6F-1EDE-51A8-B00D-029CFDFE0F38.dita">boot table</xref> function |
|
16 entries are summarised in the following table. Each is identified by its <codeph>TBootTableEntry</codeph> enumerator |
|
17 that defines its position in the table. Click the enumerator symbol for more |
|
18 detail on what the function must do. </p> |
|
19 <table id="GUID-D7774430-469D-5E6F-8419-F23DD3E517A0"> |
|
20 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
21 <tbody> |
|
22 <row> |
|
23 <entry><p> <b>Enumerator symbol</b> </p> </entry> |
|
24 <entry><p> <b>Summary description</b> </p> </entry> |
|
25 </row> |
|
26 <row> |
|
27 <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> |
|
28 <entry><p>Outputs a character to the debug port. </p> </entry> |
|
29 </row> |
|
30 <row> |
|
31 <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> |
|
32 <entry><p>Gets a list of possible RAM banks. </p> </entry> |
|
33 </row> |
|
34 <row> |
|
35 <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> |
|
36 <entry><p>Does any required setup for each RAM bank. </p> </entry> |
|
37 </row> |
|
38 <row> |
|
39 <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> |
|
40 <entry><p>Gets a list of possible ROM banks. </p> </entry> |
|
41 </row> |
|
42 <row> |
|
43 <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> |
|
44 <entry><p>Does any required setup for each ROM bank. </p> </entry> |
|
45 </row> |
|
46 <row> |
|
47 <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> |
|
48 <entry><p>Gets a list of required I/O mappings. </p> </entry> |
|
49 </row> |
|
50 <row> |
|
51 <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> |
|
52 <entry><p>Reserves physical RAM if required. </p> </entry> |
|
53 </row> |
|
54 <row> |
|
55 <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> |
|
56 <entry><p>Gets a list of configuration parameters. </p> </entry> |
|
57 </row> |
|
58 <row> |
|
59 <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> |
|
60 <entry><p>Does any final setup required before booting the kernel. </p> </entry> |
|
61 </row> |
|
62 <row> |
|
63 <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> |
|
64 <entry><p>Allocates RAM during boot. </p> </entry> |
|
65 </row> |
|
66 <row> |
|
67 <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> |
|
68 <entry><p>Gets MMU PDE permissions for a mapping. </p> </entry> |
|
69 </row> |
|
70 <row> |
|
71 <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> |
|
72 <entry><p>Gets MMU PTE permissions for a mapping. </p> </entry> |
|
73 </row> |
|
74 <row> |
|
75 <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> |
|
76 <entry><p>Called when a page table entry is updated. </p> </entry> |
|
77 </row> |
|
78 <row> |
|
79 <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> |
|
80 <entry><p>Enables the MMU. </p> </entry> |
|
81 </row> |
|
82 </tbody> |
|
83 </tgroup> |
|
84 </table> |
|
85 <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, |
|
86 where <codeph>CFG_DebugBootRom</codeph> is set to FALSE, the function should |
|
87 return immediately without doing anything. </p> <p>On debug bootstrap builds, |
|
88 where <codeph>CFG_DebugBootRom</codeph> is set to TRUE, the function should |
|
89 output a single character to the debug port. </p> <p>It may be necessary to |
|
90 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 |
|
91 correct destination for the character. The function should not modify any |
|
92 registers, but may change flags. </p> <p>This function can be called with |
|
93 the MMU either disabled or enabled. Different I/O port addresses will normally |
|
94 be required in these two cases. To simplify handling of this the following |
|
95 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 |
|
96 the physical address of the peripheral, <codeph>LINEAR</codeph> is its linear |
|
97 address. </p> <p>On the direct memory model, the <codeph>PHYSICAL</codeph> address |
|
98 is always loaded into <codeph>Rd</codeph>. On the moving or multiple memory |
|
99 models the macro performs a runtime check of the <codeph>CP15</codeph> control |
|
100 register to determine whether the MMU is enabled. If the MMU is enabled, then |
|
101 the <codeph>LINEAR</codeph> address is loaded into <codeph>Rd</codeph>, otherwise |
|
102 the <codeph>PHYSICAL</codeph> address is loaded. </p> <p>Note that <codeph>CFG_DebugBootRom</codeph> is |
|
103 set in the <xref href="GUID-2E4F8732-F253-5E0D-9A37-9476541E6004.dita">platform |
|
104 specific configuration header file</xref>. </p> <p><b>Entry conditions</b> </p><ul> |
|
105 <li id="GUID-7375F514-78DB-5620-A076-3F0D0A4E595C"><p> <codeph>R0</codeph> bottom |
|
106 8 bits contain the character to be output </p> </li> |
|
107 <li id="GUID-F6F936BB-2240-5C4E-AF93-9A5C63ACC28F"><p> <codeph>R10</codeph> points |
|
108 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
109 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
110 <li id="GUID-333CCEE2-F3EB-5800-8F12-AE33A9FAC225"><p> <codeph>R12</codeph> points |
|
111 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
112 <li id="GUID-D3BF3853-8542-5F0A-B3AC-4CCE02015C8A"><p> <codeph>R13</codeph> points |
|
113 to a valid stack. </p> </li> |
|
114 </ul> </section> |
|
115 <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 |
|
116 pointer to a list of RAM banks that are present. </p> <p>The list should be |
|
117 a sequence of two-word entries. Each entry has the following format: </p> <fig id="GUID-3B76398A-AE4C-563B-BB52-3701983D01B4"> |
|
118 <image href="GUID-921AF7A3-C711-5979-877B-4B6D977888E8_d0e5006_href.png" placement="inline"/> |
|
119 </fig> <p>The list is terminated by an entry that has a zero MAXSIZE. </p> <p>Of |
|
120 the 32 flag bits, only one is currently defined; all undefined flags should |
|
121 be zero. Flag 0, which is bit 0 of the first word is the <codeph>RAM_VERBATIM</codeph> flag |
|
122 and is interpreted as follows: </p> <ul> |
|
123 <li id="GUID-415A4838-2858-5EE5-B9F4-D55CDD9AE02C"><p>If clear, the specified |
|
124 physical address range may or may not contain RAM, and may be only partially |
|
125 occupied. In this case generic bootstrap code will probe the range to establish |
|
126 if any RAM is present, and if so, which parts of the range are occupied. This |
|
127 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 |
|
128 (greater than or equal to 64K), and BASE must be a multiple of MAXSIZE. </p> </li> |
|
129 <li id="GUID-6CB0DED5-838E-5F58-8796-A191ED7199D4"><p>If set, the specified |
|
130 physical range is known to be fully occupied by RAM, and furthermore, that |
|
131 all memory controller setup for that range has already been completed. In |
|
132 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 |
|
133 not be called for this range. </p> </li> |
|
134 </ul> <p>Note that all banks declared in this list and subsequently found |
|
135 to be occupied will be treated as standard RAM available for any purpose. |
|
136 For this reason, internal RAM or TCRAM banks are not generally included in |
|
137 the list. </p> <p><b>Entry |
|
138 conditions</b> </p> <ul> |
|
139 <li id="GUID-61BC32CF-36E0-598F-A97B-D3C1C032951C"><p> <codeph>R10</codeph> points |
|
140 to the superpage, represented by the <codeph>SSuperPageBase</codeph> struct |
|
141 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
142 <li id="GUID-156C3C48-F4C5-5E4E-9472-C273DF805061"><p> <codeph>R12</codeph> points |
|
143 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
144 <li id="GUID-16D3C3A1-CDE2-5249-95D6-B8B37C1C2C44"><p> <codeph>R13</codeph> points |
|
145 to a valid stack </p> </li> |
|
146 <li id="GUID-03864AFE-0A45-551B-ADA7-6FB530F7CB4D"><p>the MMU is disabled. </p> </li> |
|
147 </ul> <p><b>Exit |
|
148 conditions</b> </p> <ul> |
|
149 <li id="GUID-C38E1D41-7589-5368-8872-48FE33CA989A"><p> <codeph>R0</codeph> should |
|
150 contain the base address of the list of banks </p> </li> |
|
151 <li id="GUID-487A2C0B-DC61-5F7F-97FE-5065667134E0"><p> <codeph>R0</codeph> -<codeph>R3</codeph> and |
|
152 flags may be modified, but no other registers should be modified. </p> </li> |
|
153 </ul> </section> |
|
154 <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 |
|
155 setup for each RAM bank. </p> <p>This function is called <i>twice</i> for |
|
156 each RAM bank that does <i>not</i> have the <codeph>RAM_VERBATIM</codeph> flag |
|
157 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, |
|
158 and the second call is after width detection. </p> <p>This function is only |
|
159 required if the system has a complex and very variable RAM setup, for example |
|
160 several banks of potentially different widths. Typical systems have one or |
|
161 two banks of RAM of known width and all memory controller initialisation can |
|
162 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; |
|
163 in this case this function can simply return without performing any operation. </p> <p><b>Entry conditions</b> </p> <ul> |
|
164 <li id="GUID-4080EA07-03AE-5D7C-9931-71DC7A7844D6"><p> <codeph>R1</codeph> holds |
|
165 the physical base address of a bank </p> </li> |
|
166 <li id="GUID-02D174D3-A176-55A1-81C6-BEDBA72023FC"><p> <codeph> R3 = 0xFFFFFFFF</codeph> for |
|
167 the first call</p> <p> <codeph> R3 = 0x0000000Y</codeph> for the second call, |
|
168 where the bottom 4 bits represent the validity of each of the 4 byte lanes |
|
169 (bit 0=1 if D0-7 are valid, bit 1=1 if D8-15 are valid, etc.) </p> </li> |
|
170 <li id="GUID-0DD72D2D-D26D-59B1-B60B-5DA41D8B4FF0"><p> <codeph>R10</codeph> points |
|
171 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
172 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
173 <li id="GUID-7EF8D070-7843-5164-BEC5-E6EC7A2B4159"><p> <codeph>R12</codeph> points |
|
174 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
175 <li id="GUID-86030AEF-E1C5-5CCA-8E95-C9A360286609"><p> <codeph>R13</codeph> points |
|
176 to a valid stack </p> </li> |
|
177 <li id="GUID-88F1940A-A7A2-5340-8278-BB2CC269B3DE"><p>the MMU is disabled. </p> </li> |
|
178 </ul> <p><b>Exit |
|
179 conditions</b> </p> <p>Other than flags, no registers should be modified. </p> </section> |
|
180 <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 |
|
181 pointer to a list of XIP ROM banks that are present. It is not called if the |
|
182 bootstrap is found to be running in RAM; in this case it is assumed that all |
|
183 XIP code is in RAM. </p> <p>The list should be a sequence of four-word entries. |
|
184 Each entry has the following format: </p> <fig id="GUID-35A65482-24F6-5F9A-83B8-ED490F651A9A"> |
|
185 <image href="GUID-4E6520E8-4BF1-55D1-B643-81B8D2816D1D_d0e5246_href.png" placement="inline"/> |
|
186 </fig> <p>The list is terminated by a zero value four-word entry. </p> <p>Only |
|
187 the first, second and fourth words of each entry are actually used by the |
|
188 rest of the bootstrap. The third is there mainly to support autodetection |
|
189 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 |
|
190 can be used to declare ROM bank entries. </p> <p><b>Entry conditions</b> </p> <ul> |
|
191 <li id="GUID-ABFD5EA9-459A-5961-9181-FC5A15463AE7"><p> <codeph>R10</codeph> points |
|
192 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
193 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
194 <li id="GUID-888C592D-F49A-508B-80EF-E729D33C1FAE"><p> <codeph>R12</codeph> points |
|
195 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
196 <li id="GUID-CC543EA9-34B7-5806-B987-6565CD07B052"><p> <codeph>R13</codeph> points |
|
197 to a valid stack </p> </li> |
|
198 <li id="GUID-618F3F1A-E91B-55AA-80D5-D2E894720AB9"><p>the MMU is disabled. </p> </li> |
|
199 </ul> <p><b>Exit |
|
200 conditions</b> </p> <ul> |
|
201 <li id="GUID-DAC651F9-6EF3-584D-92D2-388E7EC8A13B"><p> <codeph>R0</codeph> should |
|
202 contain the base address of the list of ROM banks. </p> </li> |
|
203 <li id="GUID-F8A205C2-4605-512A-A721-B6D2506D7263"><p> <codeph>R0</codeph> -<codeph>R3</codeph> and |
|
204 flags may be modified, but no other registers should be modified. </p> </li> |
|
205 </ul> </section> |
|
206 <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 |
|
207 setup for each ROM bank. </p> <p>It is called once immediately after the call |
|
208 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 |
|
209 then it is subsequently called again for <i>each</i> ROM bank in the list |
|
210 returned by <codeph>BTF_RomBanks</codeph>. It is not called if the bootstrap |
|
211 is running in RAM. </p> <p>This function is intended to support autodetection |
|
212 of the system ROM configuration. For example, the first call with <codeph>R11</codeph> set |
|
213 to zero could be used to set the bus controller to 32 bit width to enable |
|
214 width detection to be performed on ROM banks other than the boot block. Subsequent |
|
215 per-bank calls could determine the width (possibly using an algorithm that |
|
216 repeatedly reads from the same address and checks which bits are consistent) |
|
217 and the size of the ROM bank. These would be written to the entry pointed |
|
218 by <codeph>R11</codeph> and the bus controller set up correctly for that ROM |
|
219 bank. If the bank is absent, then the size in the structure pointed to by <codeph>R11</codeph> is |
|
220 set to zero to remove it from the list. </p> <p><b>Entry conditions</b> </p> <ul> |
|
221 <li id="GUID-A13AC2C7-01EC-5A15-92F3-1ABF1FB03DD2"><p> <codeph>R10</codeph> points |
|
222 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
223 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
224 <li id="GUID-CB332F6C-1B59-5B77-8396-060C9EE413E3"><p>On the first call: </p> <ul> |
|
225 <li id="GUID-96520453-4106-55AF-A0F2-D3533594EEE9"><p> <codeph>R11</codeph> contains |
|
226 0 </p> </li> |
|
227 <li id="GUID-025A5A35-6A7E-5F84-8B05-39E6427D0F63"><p> <codeph>R0</codeph> contains |
|
228 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> |
|
229 </ul> <p>On subsequent calls: </p> <ul> |
|
230 <li id="GUID-CFAED6F6-4344-505B-920E-14B99784621A"><p> <codeph>R11</codeph> points |
|
231 to a RAM copy of the entry corresponding to the ROM bank currently being processed </p> </li> |
|
232 </ul> </li> |
|
233 <li id="GUID-4456CB76-38BA-568B-9295-C965B7B70069"><p> <codeph>R12</codeph> points |
|
234 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
235 <li id="GUID-0087F2C0-343C-5F81-AC75-DEEE357A8B54"><p> <codeph>R13</codeph> points |
|
236 to a valid stack </p> </li> |
|
237 <li id="GUID-37648CD7-CB3D-547F-BC81-B354F64CF827"><p>the MMU is disabled. </p> </li> |
|
238 </ul> <p><b>Exit |
|
239 conditions</b> </p> <p>For calls where <codeph>R11</codeph> is non-zero, the |
|
240 entry pointed to by <codeph>R11</codeph> may be modified by this function |
|
241 call. </p> <p>If the entry size for a bank is set to zero, then that bank |
|
242 is assumed not to exist, and is removed from the list of ROM banks. </p> <p>Registers <codeph>R0</codeph> -<codeph>R4</codeph> and |
|
243 flags may be modified by this function; all other registers should be preserved. </p> </section> |
|
244 <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 |
|
245 pointer to a list of required I/O mappings. </p> <p>The list should be a sequence |
|
246 of one-word and two-word entries, terminated by a zero-filled word. The entries |
|
247 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 |
|
248 for declaring I/O mappings</xref>: <codeph>HW_MAPPING</codeph>, <codeph>HW_MAPPING_EXT</codeph>, <codeph>HW_MAPPING_EXT2</codeph>, |
|
249 and <codeph>HW_MAPPING_EXT3</codeph>. </p> <p>In the template port, this is |
|
250 implemented in <filepath>os/kernelhwsrv/bsptemplate/asspandvariant/template_variant/bootstrap/template.s</filepath>. |
|
251 Find the symbol <codeph>GetHwBanks</codeph>: </p> <codeblock id="GUID-93B8920C-C244-5CEE-95B4-1F49BB1D8B19" xml:space="preserve">GetHwBanks ROUT |
|
252 ADR r0, %FT1 |
|
253 MOV pc, lr |
|
254 ... |
|
255 DCD 0 ; terminator |
|
256 </codeblock> <p>The pointer in the boot table to this list of I/O mappings |
|
257 is defined by the symbol <codeph>GetHwBanks</codeph>. </p> <codeblock id="GUID-AAC33135-33B2-5B31-8D3B-906636669310" xml:space="preserve">BootTable |
|
258 ... |
|
259 DCD GetHwBanks ; get list of HW banks |
|
260 ...</codeblock> <p>To support Level 2 cache (either L210 or L220), you |
|
261 need to add the base address of the Level 2 cache controller to the list of |
|
262 hardware banks. For example: </p> <codeblock id="GUID-F28CD3A1-CBB8-5052-ADC1-96A23FE9DA5D" xml:space="preserve">GetHwBanks ROUT |
|
263 ADR r0, %FT1 |
|
264 MOV pc, lr |
|
265 ... |
|
266 HW_MAPPING L210CtrlBasePhys, 1, HW_MULT_1M |
|
267 ... |
|
268 DCD 0 ; terminator |
|
269 </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 |
|
270 conditions</b> </p> <ul> |
|
271 <li id="GUID-74CDF102-52AD-5BE2-83BB-4486D5DCF904"><p> <codeph>R10</codeph> points |
|
272 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
273 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
274 <li id="GUID-E6B28758-C709-51E9-9604-12EF39EF95EA"><p> <codeph>R12</codeph> points |
|
275 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
276 <li id="GUID-BCA82596-751E-5045-BADA-E71659254555"><p> <codeph>R13</codeph> points |
|
277 to a valid stack </p> </li> |
|
278 <li id="GUID-5F7B169A-F4C4-587F-AD33-46CF05619113"><p>the MMU is disabled. </p> </li> |
|
279 </ul> <p><b>Exit |
|
280 conditions</b> </p> <ul> |
|
281 <li id="GUID-59BB29EB-3437-5E3A-ADC8-6AA57BD10DFA"><p> <codeph>R0</codeph> should |
|
282 contain the base address of the list of banks </p> </li> |
|
283 <li id="GUID-0CEEEA0C-58CB-5A4E-9D94-EFE0496F264F"><p> <codeph>R0</codeph> -<codeph>R3</codeph> and |
|
284 flags may be modified, but no other registers should be modified. </p> </li> |
|
285 </ul> </section> |
|
286 <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 |
|
287 RAM if required. </p> <p>It is called before the bootstrap's memory allocator |
|
288 (<xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-4C8986CB-0D5A-5D61-8A4B-DAC1B9D2C8B5">BTF_Alloc</xref>) |
|
289 is initialised to allow physical RAM to be reserved for any platform specific |
|
290 purpose. </p> <p>There are two methods available for reserving physical RAM: </p> <ol id="GUID-A68E974D-B79F-5EFF-AC43-FC068B2A0B8C"> |
|
291 <li id="GUID-37C98A1E-AD3A-5D36-BA64-B24E3EC5045A"><p>Use the generic bootstrap |
|
292 function <codeph>ExciseRamArea()</codeph>, implemented in <filepath>os/kernelhwsrv/kernel/eka/kernel/arm/bootutils.s</filepath>. |
|
293 This removes a specified region from the list of RAM blocks present in the |
|
294 system. Subsequently, the excised area will no longer be treated as RAM. If |
|
295 this method is used, then the excised areas must be a multiple of 64K in size |
|
296 and aligned to a 64K boundary. </p> <p>The following entry conditions apply |
|
297 when calling <codeph>ExciseRamArea()</codeph>: </p> <ul> |
|
298 <li id="GUID-8B81140B-36A5-5DE2-A04A-59D6889935B3"><p> <codeph>R0</codeph> = |
|
299 physical base address of the area to be excised </p> </li> |
|
300 <li id="GUID-56DCD069-6683-5585-9DB5-04F540409F18"><p> <codeph>R1</codeph> = |
|
301 size of area to be excised </p> </li> |
|
302 <li id="GUID-17C76EFB-E6C3-5645-9E92-4CBC9237EA60"><p> <codeph>R9</codeph> = <codeph>SSuperPageBase::iRamBootData</codeph> </p> </li> |
|
303 <li id="GUID-24675744-4FD7-59BE-993A-0A939682C910"><p> <codeph> R10</codeph> points |
|
304 to the super page </p> </li> |
|
305 <li id="GUID-39FF3824-78CF-5B83-904A-270E1CC5686B"><p> <codeph> R11</codeph> = |
|
306 0 </p> </li> |
|
307 <li id="GUID-2DF3FCAF-BEFC-5A87-AD8C-D38DD2A8DFA3"><p> <codeph> R13</codeph> points |
|
308 to a valid stack. </p> </li> |
|
309 </ul> </li> |
|
310 <li id="GUID-C99A07B3-BF0A-58CF-9CA1-37891380D7C5"><p>Write a list of reserved |
|
311 RAM blocks to the address passed in R11. The list should consist of two-word |
|
312 entries, the first word being the physical base address of the block and the |
|
313 second word the size. The list is terminated by an entry with zero size. The |
|
314 listed blocks will still be recognised as RAM by the kernel but will be marked |
|
315 as allocated during kernel boot. The blocks in the list should be multiples |
|
316 of 4K in size and aligned to a 4K boundary. </p> </li> |
|
317 </ol> <p>If both methods are used simultaneously, then the <codeph>ExciseRamArea()</codeph> function |
|
318 will require recalculation of the value in R11 for the second method. The |
|
319 correct value can be found by loading <codeph>R11</codeph> first with <codeph>SSuperPageBase::iRamBootData</codeph>, |
|
320 stepping forward 8 bytes at a time until an entry with a zero-filled second |
|
321 word is found, and then stepping on by a further 8 bytes. </p> <p><b>Entry conditions</b> </p> <ul> |
|
322 <li id="GUID-701D97D3-629C-5270-9E98-5677B52F12E9"><p> <codeph>R10</codeph> points |
|
323 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
324 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
325 <li id="GUID-43402496-5018-5473-859A-3B2C5289FE3B"><p> <codeph>r11</codeph> points |
|
326 to the place where the pre-allocated block list should be written </p> </li> |
|
327 <li id="GUID-E25602F8-36F8-5C49-B3A8-D2B37DD7DEB7"><p> <codeph>R12</codeph> points |
|
328 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
329 <li id="GUID-E53BCEBB-AB2A-52C5-B3C8-FDFC777EB35C"><p> <codeph>R13</codeph> points |
|
330 to a valid stack </p> </li> |
|
331 <li id="GUID-61ED18DA-CB5B-50F1-81F1-59C8EEC68E15"><p>the MMU is disabled. </p> </li> |
|
332 </ul> <p><b>Exit |
|
333 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> |
|
334 <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 |
|
335 value of a run-time configurable boot parameter. The parameter is identified |
|
336 by one of the values of the <codeph>TBootParam</codeph> enumeration, which |
|
337 is passed in <codeph>R0</codeph>. </p> <p>Typically, the function is implemented |
|
338 as follows: </p> <codeblock id="GUID-60C84CAA-3B19-5FC1-8192-05519C3E76DD" xml:space="preserve">GetParameters ROUT |
|
339 ADR r1, ParameterTable |
|
340 B FindParameter |
|
341 ParameterTable ; Include any parameters specified in TBootParam |
|
342 ; enum here if you want to override them. |
|
343 DCD BPR_x, value ; parameter number, parameter value |
|
344 DCD -1 ; terminator |
|
345 </codeblock> <p>This implementation calls the generic function <codeph>FindParameter()</codeph>, |
|
346 which performs the necessary lookup of the parameter number in the table. |
|
347 The parameter table should consist of a list of two-word entries, the first |
|
348 word being the parameter number and the second the parameter value. The list |
|
349 should be terminated by a negative parameter number. The generic function |
|
350 searches this table for the parameter value, and if found, returns it in <codeph>R0</codeph> as |
|
351 stated in <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-1981A220-876C-5BBD-A84C-E895F133B6B9">Exit |
|
352 conditions</xref>. </p> <p>Note that the address of this parameter table is |
|
353 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 |
|
354 parameter table is identified by a <codeph>TBootParam</codeph> enumeration |
|
355 value that defines its position within that table. The entries have the following |
|
356 meaning: </p> <table id="GUID-B0C82F23-2342-53FE-8CFE-E82DA628D6B5"> |
|
357 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
358 <tbody> |
|
359 <row> |
|
360 <entry><p> <b>Enumerator symbol</b> </p> </entry> |
|
361 <entry><p> <b>Summary description</b> </p> </entry> |
|
362 </row> |
|
363 <row> |
|
364 <entry><p> <codeph> BPR_InitialMMUCRClear</codeph> </p> </entry> |
|
365 <entry><p>Mask of bits to clear in MMUCR in the <codeph>InitCpu()</codeph> generic |
|
366 function. Defaults to 0xFFFFFFFF, i.e. clear all bits. </p> </entry> |
|
367 </row> |
|
368 <row> |
|
369 <entry><p> <codeph> BPR_InitialMMUCRSet</codeph> </p> </entry> |
|
370 <entry><p>Mask of bits to set in MMUCR in the <codeph>InitCpu()</codeph> generic |
|
371 function after clearing those specified by <codeph>BPR_InitialMMUCRClear</codeph>. |
|
372 Defaults to a CPU-dependent value. </p> </entry> |
|
373 </row> |
|
374 <row> |
|
375 <entry><p> <codeph>BPR_FinalMMUCRClear</codeph> </p> </entry> |
|
376 <entry><p>Mask of bits to clear in MMUCR when the MMU is enabled. Defaults |
|
377 to 0, which means do not clear any bits. </p> </entry> |
|
378 </row> |
|
379 <row> |
|
380 <entry><p> <codeph>BPR_FinalMMUCRSet</codeph> </p> </entry> |
|
381 <entry><p>Mask of bits to set in MMUCR when the MMU is enabled after clearing |
|
382 those specified in <codeph>BPR_FinalMMUCRSet</codeph>. Defaults to a CPU-dependent |
|
383 value. </p> </entry> |
|
384 </row> |
|
385 <row> |
|
386 <entry><p> <codeph>BPR_AuxCRClear</codeph> </p> </entry> |
|
387 <entry><p>Mask of bits to clear in AUXCR in the <codeph>InitCpu()</codeph> Symbian |
|
388 platform generic function. Defaults to a CPU dependent value. </p> </entry> |
|
389 </row> |
|
390 <row> |
|
391 <entry><p> <codeph>BPR_AuxCRSet</codeph> </p> </entry> |
|
392 <entry><p>Mask of bits to set in AUXCR in the <codeph>InitCpu()</codeph> Symbian |
|
393 platform generic function after clearing those specified by <codeph>BPR_InitialAUXCRClear</codeph>. |
|
394 Defaults to a CPU-dependent value. </p> </entry> |
|
395 </row> |
|
396 <row> |
|
397 <entry><p> <codeph>BPR_CAR</codeph> </p> </entry> |
|
398 <entry><p>Initial value to set for coprocessor access register if present. |
|
399 Defaults to 0. </p> </entry> |
|
400 </row> |
|
401 <row> |
|
402 <entry><p> <codeph>BPR_UncachedLin</codeph> </p> </entry> |
|
403 <entry><p>Mandatory parameter on the direct memory model, not used on other |
|
404 memory models. The value is copied into <codeph>SSuperPageBase::iUncachedAddress</codeph> for |
|
405 use by any code which needs to do an uncached memory access, usually for memory |
|
406 controller synchronisation purposes. On systems with an MMU, this address |
|
407 will be mapped as an alias of the super page and must refer to the base address |
|
408 of a 1Mb region of unused virtual address space, aligned on a 1Mb boundary. |
|
409 On a system with no MMU, this address should be the physical address of some |
|
410 uncached memory. </p> </entry> |
|
411 </row> |
|
412 <row> |
|
413 <entry><p> <codeph> BPR_PageTableSpace</codeph> </p> </entry> |
|
414 <entry><p>Used only on the direct memory model on systems with an MMU. Specifies |
|
415 the amount of RAM to reserve for page tables. Defaults to 32K. </p> </entry> |
|
416 </row> |
|
417 <row> |
|
418 <entry><p> <codeph>BPR_KernDataOffset</codeph> </p> </entry> |
|
419 <entry><p>Used only on the direct memory model. Specifies the offset from |
|
420 the base of the super page to the base of the kernel .data section. Defaults |
|
421 to 8K. </p> </entry> |
|
422 </row> |
|
423 <row> |
|
424 <entry><p> <codeph> BPR_BootLdrImgAddr </codeph> </p> </entry> |
|
425 <entry><p>Mandatory parameter for bootloader configurations; not required |
|
426 for other configurations. Specifies the physical base address of the RAM-loaded |
|
427 image. </p> </entry> |
|
428 </row> |
|
429 <row> |
|
430 <entry><p> <codeph>BPR_BootLdrExtraRAM</codeph> </p> </entry> |
|
431 <entry><p>Only used on bootloader configurations. Specifies the amount of |
|
432 'user' memory to reserve (this is in fact used to satisfy <codeph>Epoc::AllocPhysicalRam</codeph> requests, |
|
433 usually for video RAM) in the case where the RAM-loaded image is at the bottom |
|
434 of RAM and so the bootloader RAM is at the top. Defaults to 1MB. </p> </entry> |
|
435 </row> |
|
436 </tbody> |
|
437 </tgroup> |
|
438 </table> <p><b>Entry |
|
439 conditions</b> </p> <ul> |
|
440 <li id="GUID-38ED47F2-BD04-5039-8A71-81D787C6B679"><p>R0 contains the number |
|
441 identifying the required parameter; see the <codeph>TBootParam</codeph> enumerator |
|
442 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/arm/bootdefs.h</filepath>. </p> </li> |
|
443 <li id="GUID-151A442C-5903-50F5-B425-0FB80CE950B8"><p> <codeph>R10</codeph> points |
|
444 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
445 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
446 <li id="GUID-916DB071-2433-512B-A4C4-70C736DABE15"><p> <codeph>r11</codeph> points |
|
447 to the place where the pre-allocated block list should be written </p> </li> |
|
448 <li id="GUID-32D51889-00F9-5968-A3BC-A1752825B8AC"><p> <codeph>R12</codeph> points |
|
449 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
450 <li id="GUID-7F5685B5-95EA-5C03-9E92-B50B60DAA2FC"><p> <codeph>R13</codeph> points |
|
451 to a valid stack </p> </li> |
|
452 <li id="GUID-E5D06E47-BF01-51D1-BC15-AF5D588AB5A5"><p>the MMU is disabled. </p> </li> |
|
453 </ul> <p id="GUID-1981A220-876C-5BBD-A84C-E895F133B6B9"><b>Exit conditions</b> </p> <p>If |
|
454 the parameter value is specified, it should be returned in <codeph>R0</codeph> and |
|
455 the <codeph>N</codeph> flag should be cleared. </p> <p>If the parameter value |
|
456 is not specified, the <codeph>N</codeph> flag should be set. </p> <p>Registers <codeph>R0</codeph> , <codeph>R1</codeph>, <codeph>R2</codeph> and |
|
457 the flags may be modified. All other registers should be preserved. </p> </section> |
|
458 <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 |
|
459 setup required before booting the kernel. It is called at the end of the bootstrap, |
|
460 just before booting the kernel. </p> <p>The function should: </p> <ul> |
|
461 <li id="GUID-388B647D-5AD6-58FD-B78A-67DBC6B945A5"><p>Map any cache flushing |
|
462 areas required by the CPU. </p> <p>Processors that flush the data cache by |
|
463 reading dummy addresses or by allocating dummy addresses into the cache (e.g. |
|
464 StrongARM and XScale processors) will need a main cache flush area. If the |
|
465 processor has an alternate data cache (e.g. StrongARM and XScale mini data |
|
466 cache) a second flush area may be required for it. On the moving and multiple |
|
467 memory models the linear addresses used for these flushing areas are fixed |
|
468 (<codeph>KDCacheFlushArea</codeph> and <codeph>KDCacheFlushArea</codeph> +1MB |
|
469 respectively). On the direct memory model any unused linear address may be |
|
470 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 |
|
471 be written with a power of 2 at least twice the cache size and no bigger than |
|
472 half the reserved address area. A value of 0x00080000 (512KB) is usually used. </p> </li> |
|
473 <li id="GUID-B0061BBC-DEBE-5A12-B11B-39F73FFC7072"><p>Populate any super page |
|
474 or CPU page fields with platform-specific information used by the variant, |
|
475 for example addresses of CPU idle routines in the bootstrap. Routines can |
|
476 be placed in the bootstrap if known alignment is required for the routine. </p> </li> |
|
477 </ul> <p><b>Entry |
|
478 conditions</b> </p> <ul> |
|
479 <li id="GUID-61AA6724-B809-5742-A6FD-F39D5269B2EE"><p> <codeph>R10</codeph> points |
|
480 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
481 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/kernboot.h</filepath> </p> </li> |
|
482 <li id="GUID-B58A49E2-B4AA-53D4-816A-B48491A707D8"><p> <codeph>r11</codeph> points |
|
483 to the kernel image header, a <xref href="GUID-88C84EC0-B63E-3848-82BF-E3A81E2F7E9A.dita"><apiname>TRomImageHeader</apiname></xref> object </p> </li> |
|
484 <li id="GUID-34A71E2F-9232-5DAF-AF04-D51822B65E8D"><p> <codeph>R12</codeph> points |
|
485 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
486 <li id="GUID-38C918F2-9769-55EC-A9F1-5D64CCB6EA2B"><p> <codeph>R13</codeph> points |
|
487 to a valid stack </p> </li> |
|
488 <li id="GUID-538DE8FF-2BE4-5D50-933C-F6D7E94A3CC1"><p>the MMU is disabled. </p> </li> |
|
489 </ul> <p><b>Exit |
|
490 conditions</b> </p> <p>Registers <codeph>R0</codeph> to <codeph>R9</codeph> and |
|
491 flags may be modified; other registers should be preserved. </p> </section> |
|
492 <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 |
|
493 function is called at various points to initialise the memory allocator, or |
|
494 to allocate physical RAM. A generic implementation is provided for this function |
|
495 and this will normally be sufficient, so a typical implementation for this |
|
496 function reduces to: </p> <codeblock id="GUID-90A5743F-4FB5-59A4-9FC8-DAB2CCDF8EB0" xml:space="preserve">DCD HandleAllocRequest</codeblock> <p>in |
|
497 the boot table. For systems with no MMU, the function name should be changed |
|
498 to <codeph>AllocatorStub</codeph>. </p> <p>It is advisable not to override |
|
499 this function. </p> <p><b>Entry |
|
500 conditions</b> </p> <ul> |
|
501 <li id="GUID-72DBAE17-60F1-5EF1-B9B1-2E69E109FE3B"><p>R2 contains the type |
|
502 of allocation required; this is defined by one of the values of the <codeph>TBootMemAlloc</codeph> enumeration </p> </li> |
|
503 <li id="GUID-70690B58-7B7B-51CE-A678-F25222CC6664"><p>R4 contains the size |
|
504 to allocate (as a log to base 2) for allocations of type <codeph>BMA_Kernel</codeph> </p> </li> |
|
505 <li id="GUID-C993DE47-01D2-5D7F-98FE-5CAEDAF16079"><p> <codeph>R10</codeph> points |
|
506 to the super page, represented by the <codeph>SSuperPageBase</codeph> struct |
|
507 defined in <filepath>os\kernelhwsrv\kernel\eka\include\kernel\kernboot.h</filepath> </p> </li> |
|
508 <li id="GUID-030F04FA-1919-5643-A634-60E9A9228FA9"><p> <codeph>R12</codeph> points |
|
509 to the ROM header, a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object </p> </li> |
|
510 <li id="GUID-DB3E70CC-7B35-5952-BE93-5A47674F3A5A"><p> <codeph>R13</codeph> points |
|
511 to a valid stack </p> </li> |
|
512 <li id="GUID-7D7962A8-57A0-5F16-9651-0A0E71F1605C"><p>the MMU may be enabled |
|
513 or disabled. </p> </li> |
|
514 </ul> <p>The type of allocation required is defined by the value of the enumerator <codeph>TBootMemAlloc</codeph>, |
|
515 defined in <filepath>os/kernelhwsrv/kernel/eka/include/kernel/arm/bootdefs.h</filepath>. |
|
516 The allocation types are as follows: </p> <table id="GUID-756C039B-D079-5EFC-B3A6-37675FD4CCBC"> |
|
517 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
518 <tbody> |
|
519 <row> |
|
520 <entry><p> <b>Enumerator symbol</b> </p> </entry> |
|
521 <entry><p> <b>Summary description</b> </p> </entry> |
|
522 </row> |
|
523 <row> |
|
524 <entry><p> <codeph>BMA_Init</codeph> </p> </entry> |
|
525 <entry><p>Called to initialise the memory allocator. </p> </entry> |
|
526 </row> |
|
527 <row> |
|
528 <entry><p> <codeph>BMA_SuperCPU </codeph> </p> </entry> |
|
529 <entry><p>Should return the physical address of the super page in R0. </p> </entry> |
|
530 </row> |
|
531 <row> |
|
532 <entry><p> <codeph>BMA_PageDirectory</codeph> </p> </entry> |
|
533 <entry><p>Should return the physical address of the page directory in R0. </p> </entry> |
|
534 </row> |
|
535 <row> |
|
536 <entry><p> <codeph>BMA_PageTable</codeph> </p> </entry> |
|
537 <entry><p>Allocate a new page table (1KB size and 1KB alignment) and return |
|
538 its physical address in R0. It is not necessary to clear the page table here. </p> </entry> |
|
539 </row> |
|
540 <row> |
|
541 <entry><p> <codeph>BMA_Kernel</codeph> </p> </entry> |
|
542 <entry><p>Allocate a page of size 2R4. This must be a valid processor page |
|
543 size; on ARM this means R4=12, 16 or 20. The returned physical address will |
|
544 be a multiple of 2R4. If no page of the requested size can be allocated a |
|
545 page of the largest possible smaller size will be allocated and R4 will be |
|
546 modified accordingly.<note>If no page of any size can be allocated this call |
|
547 will fault the system.</note> </p> </entry> |
|
548 </row> |
|
549 <row> |
|
550 <entry><p> <codeph>BMA_Reloc</codeph> </p> </entry> |
|
551 <entry><p>Called when the allocator data structures need to be relocated in |
|
552 memory. On entry R0 contains the offset to apply to all pointers (that is, |
|
553 the new address of data minus the old address). It is assumed that all the |
|
554 allocator data is contained in the super page or CPU page and that there are |
|
555 no pointers to areas which could be relocated independently. </p> </entry> |
|
556 </row> |
|
557 </tbody> |
|
558 </tgroup> |
|
559 </table> <p><b>Exit |
|
560 conditions</b> </p> <p> <codeph>R0</codeph> and flags may be modified. For <codeph>BMA_Kernel</codeph> allocations, <codeph>R4</codeph> may |
|
561 also be modified. All other registers should be preserved. </p> </section> |
|
562 <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 |
|
563 points to translate a standardised permission descriptor along with the size |
|
564 of mapping required to the PDE permission/attribute bits needed for such a |
|
565 mapping. A standardised permission descriptor can be either an index into |
|
566 the boot table (for any of the standard permission types) or the value generated |
|
567 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 |
|
568 generic implementation is provided for this function and it should not be |
|
569 necessary to override it. A typical implementation for this function then |
|
570 just reduces to: </p> <codeblock id="GUID-57B1277B-B322-506B-A5EC-A4D10C5FA420" xml:space="preserve">DCD GetPdeValue</codeblock> <p>in |
|
571 the boot table. </p> <p>Note that for systems with no MMU, this function is |
|
572 not required. </p> </section> |
|
573 <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 |
|
574 points to translate a standardised permission descriptor along with the size |
|
575 of mapping required to the PTE permission/attribute bits needed for such a |
|
576 mapping. A standardised permission descriptor can be either an index into |
|
577 the boot table (for any of the standard permission types) or the value generated |
|
578 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 |
|
579 generic implementation is provided for this function and it should not be |
|
580 necessary to override it. In the boot table, a typical implementation for |
|
581 this function then reduces to: </p> <codeblock id="GUID-E0836362-3BAE-54CB-9A1E-C81C1E823550" xml:space="preserve">DCD GetPteValue</codeblock> <p>Note |
|
582 that for systems with no MMU, this function is not required. </p> </section> |
|
583 <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 |
|
584 a PDE or PTE is updated. It performs whatever actions are required to make |
|
585 sure that the update takes effect. This usually means draining the write buffer |
|
586 and flushing the TLB (both TLBs on a Harvard architecture system). </p> <p>A |
|
587 generic implementation is provided for this function and it should not be |
|
588 necessary to override it. In the boot table, a typical implementation for |
|
589 this function then reduces to: </p> <codeblock id="GUID-FE889B79-013E-5A93-8ED0-51BEB97623A4" xml:space="preserve">DCD PageTableUpdate</codeblock> <p>Note |
|
590 that for systems with no MMU, this function is not required. </p> </section> |
|
591 <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 |
|
592 the MMU and thereby switch from operating with physical addresses to operating |
|
593 with virtual addresses. </p> <p>A generic implementation is provided for this |
|
594 function and it should not be necessary to override it. In the boot table, |
|
595 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 |
|
596 that for systems with no MMU, this function is not required. </p> </section> |
|
597 </conbody></concept> |