<?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-F67FA7B5-F6D1-5C5C-8E10-A8E317A778E4" xml:lang="en"><title>Public

Functions</title><shortdesc>Describes how to implement the three exported functions of the

platform-specific layer.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-C111DA06-F7EE-5E70-8D86-26BA2213B506"><title><codeph>InitialiseHardware()</codeph></title> <p>See

the Template port (<filepath>os/kernelhwsrv/bsptemplate/asspandvariant/template_variant/bootstrap/template.s</filepath>)

to see how this function is coded in practice. </p><p>The code can be found

at the label: </p><codeblock id="GUID-A8AF4F2B-735C-56A7-A0F0-22861C7B25DB" xml:space="preserve">    ...

    EXPORT    InitialiseHardware

InitialiseHardware    ROUT

    ...</codeblock> <p><b>Entry

conditions</b> </p><p>This function is called immediately after reset with

the CPU in supervisor mode, with all interrupts disabled, and <codeph>R12</codeph> pointing

to the ROM header (a <xref href="GUID-DE701BC5-4AA8-345F-BDD5-5737DB8C0098.dita"><apiname>TRomHeader</apiname></xref> object). There is no valid

stack on entry to this function, i.e. <codeph>R13</codeph> is undefined. </p><p><b>What the function should do</b> </p><p>The function is intended to perform

the basic hardware initialisation that is required immediately after reset.

It also sets up the address of the <xref href="GUID-9595FD6F-1EDE-51A8-B00D-029CFDFE0F38.dita">boot

table</xref>. </p><p>In detail, it should: </p> <ol id="GUID-59A1A7B0-E06E-5C32-B860-E8B93C9CF66B">

<li id="GUID-8993124C-D161-5BF6-9B1E-AE7A1ED2261C"><p>Initialise the CPU/MMU

registers. This is done by making a call to the generic function <codeph>InitCpu()</codeph>,

passing the address of the boot parameter table. For more information on the

boot parameter table, see <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-4DEA1D4C-EC7B-5F9A-A293-A7F80899044B">BTF_Params</xref>,

which is one of the <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita">boot

table functions</xref>. </p> <p> <codeph>InitCpu()</codeph> flushes all caches,

sets up the MMU control registers, and enables the instruction cache (on a

split cache device). Note that <codeph>R14</codeph> needs to be preserved

before making the function call. As there is no valid stack, R14 is typically

saved in R13. </p> </li>

<li id="GUID-D17DE836-C90C-5021-9A4B-BD9C9C047CB2"><p>Interrogate the hardware

to determine the reset reason. In a transparent reset, all RAM contents are

preserved and the reset should be invisible to the user, for example waking

up from a low power mode such as the SA1110 sleep mode. In this case, perform

whatever device-dependent sequence is required to restore the processor state,

and jump back into the power down code: <codeph>InitialiseHardware()</codeph> will

never return to the generic boot code. </p> <p>For bootloader bootstraps,

if the reset reason is <i>power on reset</i> or <i>hardware cold reset</i>,

or if it is a <i>software reset</i> and a rerun of the bootloader was requested

(i.e. <codeph>Kern::Restart()</codeph> was called with a parameter value of <codeph>0x80000000</codeph>),

then proceed to step 3. If these conditions are not true, for example when

the reset reason is <i>software reset</i> with any other parameter value or

a reset caused by waking up from a low power mode, then control should immediately

be transferred to the image already loaded. The state of the system at the

point where control is transferred should be as close as possible to the state

immediately after reset, to provide proper conditions for the bootstrap in

the already loaded image. </p> <p>If the system contains FLASH memory which

can be programmed with a ROM image, an additional check may be needed to see

if an image already present in FLASH should be run instead of the bootloader

following a hardware reset. A spare switch on the board is often used for

this purpose. </p> </li>

<li id="GUID-E017D1A4-389C-54B1-A2CF-D5E42A36AF3A"><p>Initialise enough hardware

to satisfy the rest of the bootstrap. The precise split between what is initialised

here, what is initialised later in the bootstrap, and what is done during

variant initialisation is flexible, but as an absolute minimum this function

must make some RAM accessible. Typically this function should set up ROM and

RAM controllers, set the CPU clock frequency, set sensible states for GPIO

lines and set up whatever bus controller is necessary to communicate with

any external peripheral chips present. Note also that it is often useful to

allow the ROM image to run from either ROM or RAM - this is one of the main

reasons for making the bootstrap position independent. To allow for this,

the intialisation code must check the PC when setting up the memory controllers;

if code is already running from RAM then RAM must already have been initialised

and it may not be necessary to touch the RAM controller. </p> </li>

<li id="GUID-17E0D947-0F65-587C-A05C-AFCB4784C5EF"><p>Determine the physical

address of the super page. This will usually be at the beginning of physical

RAM, unless there is a good reason for it not to be. The main reason why the

super page might not be at the beginning of physical RAM is usually because

either that address is reserved for hardware (e.g. video RAM), or that code

is running from that address. <codeph>R10</codeph> should be loaded with the

physical address determined. Note that, if it is not possible to determine

the final address of the super page here, a temporary address can be used

and the super page relocated to its final address later on. See <xref href="GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE.dita#GUID-B3F6FC45-3BF0-5F92-8325-44C705BA47AE/GUID-4C8986CB-0D5A-5D61-8A4B-DAC1B9D2C8B5">BTF_Alloc</xref> for more detail. </p> <p>The super page is defined by the <codeph>SSuperPageBase</codeph> struct

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

<li id="GUID-D31E7F12-0E3E-5100-A2C8-1C0901743241"><p>Fill in valid values

for the following minimum set of super page fields: </p> <ul>

<li id="GUID-9EF8675B-56CD-5F22-A1BC-5DA7E8B9815D"><p> <codeph>iBootTable</codeph> should

contain the address of the <xref href="GUID-9595FD6F-1EDE-51A8-B00D-029CFDFE0F38.dita">boot

table</xref>. </p> </li>

<li id="GUID-AEC1640A-D28E-5835-8300-093D5EE3BB8F"><p> <codeph>iCodeBase</codeph> should

contain the base address of the bootstrap code. It is used to resolve offset

addresses such as those in the boot table. </p> </li>

<li id="GUID-00172B3D-94CE-519D-A560-1F54EAED3723"><p> <codeph>iActiveVariant</codeph> is

the hardware variant discriminator (such as 05040001) for the hardware platform

in use. It is used to find the corresponding primary (kernel) executable image. </p> </li>

<li id="GUID-6A8D97CE-0B64-5F12-8220-695C64AEC0A3"><p> <codeph>iCpuId</codeph> should

be set to the value of the CP15 main ID register, obtained by MRC P15, 0,

Rd, C0, C0, 0. </p> </li>

</ul> </li>

<li id="GUID-CE64A7CA-E90E-5CC5-9993-C2CFCD7430D8"><p>The super page field <codeph>iMachineData</codeph> is

used to communicate hardware-specific data between the bootstrap and the variant.

It must be set to point to somewhere in the super page or CPU page. Typically,

it points to the beginning of the CPU page. </p> </li>

<li id="GUID-BD601948-A9E6-5111-8468-38183E507819"><p>The super page field <codeph>iHwStartupReason</codeph> is

used to pass the detailed reset reason to the variant. It is a hardware specific

value. </p> </li>

<li id="GUID-968C3623-9C19-579B-BBB2-7DFEB73ED27B"><p>In debug builds of the

bootstrap, as indicated by the symbol <codeph>CFG_DebugBootRom</codeph> being <codeph>TRUE</codeph>,

the debug tracing port should be initialised here. See also <xref href="GUID-2E4F8732-F253-5E0D-9A37-9476541E6004.dita">Platform-Specific

Configuration Header</xref>. </p> </li>

<li id="GUID-022CAC0D-75E5-5D9F-A3DC-82CEEF62A2CC"><p>If Level 2 cache is

included in the bootstrap (i.e. specifically L210 cache or L220 cache), then: </p> <ul>

<li id="GUID-A4F41EF7-88D6-53CE-B09F-B26709CCEC93"><p>the function must initialise

the cache. This involves setting cache properties: size, type, N-ways and

cache invalidation. The following code is an example of L210 cache initialisation,

but it is also valid for L220 cache initialisation: </p> <codeblock id="GUID-3290ED70-4A4B-5205-B8EE-7065E574B5A8" xml:space="preserve">;Configure L2 cache

;-------------------

    LDR     r0, =L210CtrlBasePhys    ; Base phys. addr. of L210 Cache Controller

    ;Set L210 Control Register 

    LDR r1, #L210CTRLReg        ; L210CTRLReg comes from Ref.Manual

    STR r1, [r0, #0x104]  ; 104h is address offset of Control Register

    ;Invalidate entire L2 cache by way (8 ways are presumed)

    MOV r1, #0xFF

    STR r1, [r0, #0x77c]  ; 77Ch is address offset of InvalidateByWay Register

    ;Loop while invalidate is completed

_L2loop

    LDR r1, [r0, #0x77c]

    CMP r1, #0    

    BNE _L2loop

</codeblock> </li>

<li id="GUID-14AABD62-2C28-5858-BD8A-DD783EE60E2A"><p>the superpage field <xref href="GUID-0D646171-1989-39F0-A254-5B6D060D8C25.dita#GUID-0D646171-1989-39F0-A254-5B6D060D8C25/GUID-D0AD6575-8912-30E0-ADB8-17FB435290FF"><apiname>SSuperPageBase::iArmL2CacheBase</apiname></xref> must

be set to the base physical address of the L2 cache control area, like in

the following example: </p> <codeblock id="GUID-B52C68DF-F321-5F51-811A-A60765B6F3F9" xml:space="preserve">    ;Initialise SSuperPageBase::iArmL2CacheBase

    ;------------------------------------------

    LDR r0, =L210CtrlBasePhys    ; this is base physical address of L210 cache controller

    STR r0, [r10, #SSuperPageBase_iArmL2CacheBase];r10 holds the base address of super page

</codeblock> <p>Note that the superpage is defined by the <xref href="GUID-0D646171-1989-39F0-A254-5B6D060D8C25.dita"><apiname>SSuperPageBase</apiname></xref> struct

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

</ul></li>

</ol><p><b>Exit

conditions</b> </p><p>The function can modify any CPU registers subject to

the conditions that: </p><ul>

<li id="GUID-CF4947C7-F581-51AF-A154-183516C29E2C"><p>it returns in supervisor

mode with all interrupts disabled </p> </li>

<li id="GUID-E9D9500E-347F-5A7F-A4A8-5F4DF1FAD4C8"><p>it returns the physical

address of the super page in <codeph>R10</codeph>. </p> </li>

</ul> </section>

<section id="GUID-F8351937-F6F1-5CC0-A4F1-1EF05B155330"><title>Fault()</title> <p><b>Entry conditions</b> </p> <p>The processor state is completely undefined

except that <codeph>R14</codeph> of the current mode points to the instruction

after the fault. </p> <p><b>What

the function should do</b> </p> <p>This function is called if a fatal error

is detected during boot. </p> <p>The implementation should halt the system

and produce whatever diagnostics are possible. Typically, if debug tracing

is enabled, the CPU state can be dumped over the debug port. A generic function

is provided to do this, as the minimal implementation is simply: </p> <codeblock id="GUID-B1266ACD-6862-5074-B684-9A9D764B6842" xml:space="preserve">        EXPORT Fault

Fault    ROUT

        B BasicFaultHandler ; generic handler dumps registers via

                            ; debug serial port

</codeblock> </section>

<section id="GUID-BC227FC6-8F59-5CE2-8970-A287A2CD1AEE"><title>RestartEntry()</title> <p><b>Entry conditions</b> </p> <p>On entry the CPU state is indeterminate,

as the restart may be caused by a kernel fault, with the exception that <codeph>R0</codeph> contains

the reboot reason, the parameter passed to <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-936EA5BE-DBBE-3298-9F77-0384886E058A"><apiname>Kern::Restart()</apiname></xref>. </p> <p>This

value is hardware specific except for the following two values: </p> <ul>

<li id="GUID-7414830B-7758-5834-A47F-13A674D11443"><p> <codeph> 0x00000000</codeph> means

restart the same ROM image, preserving RAM contents if possible. </p> </li>

<li id="GUID-0A55988A-FF04-55E0-99A7-E73C7F2433C3"><p> <codeph>0x80000000</codeph> means

restart the boot loader and load a new image. This code is generated by the

crash debugger in response to the <xref href="GUID-08E14B34-5144-5AA8-AA55-7AF03671676C.dita#GUID-08E14B34-5144-5AA8-AA55-7AF03671676C/GUID-4E12A080-AC83-5872-A66D-4C14A65C5CFA">X

command</xref> of the crash debugger. </p> </li>

</ul> <p><b>What

the function should do</b> </p> <p>The function is called by the kernel when

a system restart is required, and should perform whatever actions are necessary

to restart the system. If possible, a hardware reset should be used. Failing

that, it should reset all peripheral controllers and CPU registers, disable

the MMU and jump back to the reset vector. </p> </section>