<?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-C376486D-B9BF-5D00-8B1A-1527FC1F83AD" xml:lang="en"><title>RAM

Zone Tutorial</title><shortdesc>This topic describes how to design the use of RAM zones on a phone,

and how to specify the RAM zones in the set up functions in the ASSP/Variant. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A base port can improve the power performance of a phone through the use

of <xref href="GUID-C13DFF33-7C54-5113-9277-CAD96215F075.dita">RAM Zones</xref>. </p>

<section id="GUID-7A1812EA-F693-4521-A72D-A7AF95B61C66"><title> Specifying RAM zones</title> <p>RAM zones are specified only

once during the boot process by the base port. This takes place within the

overridden pure virtual method <xref href="GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D.dita#GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D/GUID-63F2135B-4264-3B3B-9B68-656A89BF7EE9"><apiname>Asic::Init1()</apiname></xref> by <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-F4765A82-01D0-3F97-A216-99327F14D53A"><apiname>Epoc::SetRamZoneConfig()</apiname></xref>. <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-F4765A82-01D0-3F97-A216-99327F14D53A"><apiname>Epoc::SetRamZoneConfig()</apiname></xref> takes an array of <xref href="GUID-9C26C2ED-922E-3E61-9A7D-779165940BB9.dita"><apiname>SRamZone</apiname></xref> objects and an optional pointer

to the base port implementation of the <xref href="GUID-ACA7BAC8-9DC3-356A-92C2-F33A99D8604B.dita"><apiname>TRamZoneCallback</apiname></xref> function.

This is described in detail in <xref href="GUID-C376486D-B9BF-5D00-8B1A-1527FC1F83AD.dita#GUID-C376486D-B9BF-5D00-8B1A-1527FC1F83AD/GUID-A0273264-8876-523D-B1F0-F6D430FFAECA">RAM

zone call back function</xref>. </p> <p>Each <xref href="GUID-9C26C2ED-922E-3E61-9A7D-779165940BB9.dita"><apiname>SRamZone</apiname></xref> object

contains the physical base address, size in bytes, unique ID, preference value

and a set of flags for each RAM zone. </p> <p><b>Restrictions on RAM zone

properties </b> </p> <p>There are some restrictions on how the base port can

specify the RAM zones: </p> <ul>

<li id="GUID-CD39AC9D-D625-548E-8AFC-DCF567AE5D90"><p>each RAM zone's address

space must be distinct and not overlap with any other RAM zone's address space </p> </li>

<li id="GUID-9A43168A-D350-5A83-A201-683C0DEC5D51"><p>the value of <xref href="GUID-F17B80B9-82E2-32FB-8AE0-10FE8094910F.dita"><apiname>SRamZone.iBase</apiname></xref> must

be aligned to the ASIC's MMU small page size </p> </li>

<li id="GUID-D7F43ADD-22DC-504E-BAB1-BAFB5B10D59C"><p>the value of <xref href="GUID-369C0E92-AE5D-3939-9D41-8269CA1842B0.dita"><apiname>SRamZone.iSize</apiname></xref> must

be a multiple of the ASIC's MMU small page size, usually 4KB on an ARM MMU </p> </li>

<li id="GUID-6CA82A2B-1812-5F01-8BDD-458EEF0012AE"><p>when added together

all of the RAM zones must cover the whole of the physical RAM address space

as specified by the bootstrap in the <xref href="GUID-84750794-1480-349B-8E93-442A98FCA2E9.dita"><apiname>SuperPage</apiname></xref> member <xref href="GUID-0D646171-1989-39F0-A254-5B6D060D8C25.dita#GUID-0D646171-1989-39F0-A254-5B6D060D8C25/GUID-10EBE3FB-68EE-3367-9244-65E555032F57"><apiname>SSuperPageBase::iTotalRamSize</apiname></xref>  </p> </li>

<li id="GUID-B8C7068C-33DC-5524-8A1D-CE36CF188487"><p>the value of each RAM

zone’s <xref href="GUID-5C496D97-236F-3EEA-850E-C34F8460CBE4.dita"><apiname>SRamZone.iId</apiname></xref> must be unique for that RAM zone </p> </li>

<li id="GUID-C0840320-5F65-5D11-981F-04BED75E3E60"><p>there can be no more

RAM zones than specified by <xref href="GUID-F7BFCBAF-3E13-3F2F-B89F-F4F7DE40E204.dita"><apiname>KMaxRamZones</apiname></xref>. </p> </li>

</ul> <p><b>Restriction on RAM zone preference ordering </b> </p> <p>The bootstrap

always allocates the RAM it requires from the lowest RAM address upwards.

This is during the system boot process and before the variant has specified

the RAM zone properties. This means that the RAM zone(s) located at the lowest

RAM addresses, used by the bootstrap, are never empty. Therefore, these RAM

zone(s) should always be assigned to be the most preferable. A low preference

value maps to a high logical preference, therefore the most preferable RAM

zones have a preference value that is lower than the preference value of all

the other RAM zones in the device. </p> </section>

<section id="GUID-68EA70F2-91DD-5919-97D5-7A5678E16FC8"><title>Designing RAM

zones to reduce power consumption</title> <p><b>Partitioning RAM into zones </b> </p> <p>For

power saving purposes, each RAM zone should represent the lowest division

of the device’s RAM IC(s) that can be either powered down or refreshed independently

of other divisions of the RAM IC(s). For example, it should not be possible

for less than an entire RAM zone to be powered or refreshed. This allows the

system to achieve lower power consumption when the level of RAM usage is reduced. </p> <p>For

example, if a device contains two RAM ICs and each IC is further divided into

4 banks that can be refreshed independently, then the device’s RAM should

be divided into 8 RAM zones with each zone being mapped to one of the 8 individually

refreshable RAM IC banks. </p> <p><b>Assigning preferences to zones </b> </p> <p>To

save power, the RAM zone preferences should be implemented in such a way that

the minimum number of RAM ICs or RAM IC refresh banks are used. </p> <p>For

example, suppose a device has 2 RAM ICs, the RAM zones in the lowest addressed

RAM IC (IC0) should be more preferable than the RAM zones located in the second

RAM IC (IC1). For all RAM zones in IC0 the preference should be less than

the preference of the RAM zones in IC1. A zone with a lower preference being

the preferred RAM zone. This results in RAM IC1 only being powered on once

RAM IC0 is too full. This is determined by the RAM zone thresholds. </p> <p><b>RAM

zone power state on system boot </b> </p> <p>When the system boots, all the

RAM specified by the bootstrap must be enabled and ready to use. Devices that

wish to reduce power consumption must only adjust the power modes(s) of the

RAM IC(s) after the RAM zone call back function has been invoked with aOp=<xref href="GUID-1DB1634C-F3D6-382B-B742-CB61FD5383C6.dita"><apiname>ERamZoneOp_Init</apiname></xref>. </p> </section>

<section id="GUID-5EBF1D4D-A86C-5FBF-ADA8-8551284DF665"><title>Designing RAM

zones for physically contiguous allocation</title> <p>Some devices have particular

applications or hardware peripherals that require a block of physically contiguous

RAM. In such cases, a RAM zone should be defined that is the size of the physically

contiguous block required, aligned to the nearest ASIC’s MMU small page size.

The device then attempts to use this RAM zone whenever the particular application

or hardware peripheral is activated. </p> <p>For example, a device may contain

a camera that requires a buffer of 4MB of physically contiguous memory to

operate. A RAM zone with a size of 4MB must be defined and this RAM zone should

have a greater preference value than other RAM zones in the device. This results

in the camera RAM zone: </p> <ul>

<li id="GUID-F573D85A-0207-5BB4-8089-717A8B07AF2A"><p>only being used for

non-camera purposes once all of the other RAM zones in the device become too

full. </p> </li>

<li id="GUID-1EFFD42D-F1EF-5B7D-B34D-C5D185CDD23E"><p>having a greater chance

of being emptied of any pages allocated for non-camera purposes when required

by the camera. </p> </li>

</ul> <p><b>KRamZoneDiscardOnly </b> </p> <p>On devices that use <xref href="GUID-469EC7BB-8697-57FE-A487-016882A0BEA8.dita">demand

paging</xref>, an additional way to increase the chances of a RAM zone being

available is to set the <xref href="GUID-A0A5E53C-C454-37C4-9314-941B8A9F64E5.dita"><apiname>KRamZoneDiscardOnly</apiname></xref> bit of <xref href="GUID-9C26C2ED-922E-3E61-9A7D-779165940BB9.dita"><apiname>SRamZone</apiname></xref> s' <xref href="GUID-61FE6994-3FBE-3512-A2C4-08AE33B3B41D.dita"><apiname>iFlags</apiname></xref> member.

This stops the system allocating pages that are not discardable in that zone.

However, setting <xref href="GUID-A0A5E53C-C454-37C4-9314-941B8A9F64E5.dita"><apiname>KRamZoneDiscardOnly</apiname></xref> also has the effect

of reducing the amount of RAM available to the device for general purpose

(non-demand paging) use. </p> <p> <xref href="GUID-C926F405-1AC2-33E7-9031-A4A22F19D5F7.dita"><apiname>KRamZoneFlagDiscardOnly</apiname></xref> only

increases the chances of a RAM zone’s availability if the minimum buffer size

used by demand paging and/or file caching, is small enough that the RAM zone

may be cleared without reducing the paging or caching buffer beyond their

specified minimum size. </p> </section>

<section id="GUID-A0273264-8876-523D-B1F0-F6D430FFAECA"><title>RAM zone call

back function</title> <p>If <xref href="GUID-ACA7BAC8-9DC3-356A-92C2-F33A99D8604B.dita"><apiname>TRamZoneCallback</apiname></xref> has been initialised

by <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-F4765A82-01D0-3F97-A216-99327F14D53A"><apiname>Epoc::SetRamZoneConfig()</apiname></xref>, then it is invoked each time

the system requires the base port to perform an operation on a RAM zone. When

the call back function is invoked the calling thread is: </p> <ul>

<li id="GUID-46E21179-B438-5C2F-9CAD-E6388A1E08D8"><p>in a critical section </p> </li>

<li id="GUID-6731F7EF-3407-5DEE-8886-B44B042570A1"><p>holding the Symbian

platform RAM allocator mutex </p> </li>

<li id="GUID-217193FE-008E-57BC-A9BC-B6D68C88F521"><p>not holding any fast

mutex </p> </li>

<li id="GUID-D193EE0B-7E8C-5E18-9998-735BE7E36BBD"><p>interrupt enabled and

the kernel is unlocked. </p> </li>

</ul> <p>This means that the base port’s implementation of the call back function

is: </p> <ul>

<li id="GUID-28CC9F46-A680-503C-B222-E857D9806818"><p>not able to be suspended

or killed by another thread </p> </li>

<li id="GUID-210F0AA9-E1D4-5801-A4A9-8A901D213C00"><p>not able to acquire

a Symbian platform mutex of an order greater than or equal to the RAM allocator

mutex this is all other Symbian platform mutexes. This is a deadlock prevention

mechanism. </p> </li>

<li id="GUID-FCADE0F8-5B71-54C9-85B3-BA963B942572"><p>able to acquire a fast

mutex. The call back must release it before returning. </p> </li>

<li id="GUID-4181E193-B030-55E0-AAD5-4687B6B9547D"><p>able to be pre-empted

by other threads/processes. </p> </li>

</ul> <p><b>Parameters </b> </p> <p>A choice of three RAM zone operations

can be requested with <xref href="GUID-ACA7BAC8-9DC3-356A-92C2-F33A99D8604B.dita"><apiname>TRamZoneCallback</apiname></xref>, as defined by <xref href="GUID-445BC66E-44AF-3F56-8E8B-CD3C22C0FF8B.dita"><apiname>TRamZoneOp</apiname></xref>: </p> <ul>

<li id="GUID-39D99FE2-CB23-5D41-A9DD-9353684C7B3F"><p> <xref href="GUID-3B839FD3-BA8B-38A0-A850-62491C71D3E3.dita"><apiname>ERamZoneOp_PowerUp</apiname></xref> is

used each time a RAM zone transitions from being empty to having pages allocated

into it. When this operation is invoked, all RAM zones that have their bit

position set in the mask pointed to by <codeph>aParam2</codeph>  <i>MUST</i> be

fully enabled and ready for use before returning from the call back function.

Failure to fully enable any of these RAM zones results in the device becoming

unstable and its behaviour unpredictable. </p> <p>For example, a device could

have two RAM ICs, where IC1 is mapped to RAM zones 1 - 4 and IC2 is mapped

to RAM zones 5 - 8. </p> <p>If while the second RAM IC is powered down, RAM

zone 5 is required, a <xref href="GUID-3B839FD3-BA8B-38A0-A850-62491C71D3E3.dita"><apiname>ERamZoneOp_PowerUp</apiname></xref> operation is requested.

The IC2 must be fully enabled before returning from the call back function.

On return from the call back function, the memory in IC2 is used by the system. </p> </li>

<li id="GUID-25B72080-8E39-5739-9545-8D17AE8EA669"><p> <xref href="GUID-74DA7B02-CB90-325D-8A84-454004AEB5C8.dita"><apiname>ERamZoneOp_PowerDown</apiname></xref> is

used each time a RAM zone transitions from having pages allocated in it to

being empty. Devices that wish to reduce power consumption can adjust a RAM

IC’s partial array self refresh mode or power down a RAM IC if all of the

other RAM zones in that RAM IC are also empty. </p> <p>For example, an <xref href="GUID-74DA7B02-CB90-325D-8A84-454004AEB5C8.dita"><apiname>ERamZoneOp_PowerDown</apiname></xref> operation

is requested when all the RAM zones mapped to the top half of the RAM IC Partial

Array Self Refresh (PASR) regions are empty. The RAM IC can be set to use

half array PASR when it next enters PASR mode, assuming the RAM IC has the

option of using half array PASR mode. </p> </li>

<li id="GUID-FC3EBDE2-64E5-5AA1-938F-858C62D18A56"><p> <xref href="GUID-2A00ADB4-778F-3981-A9DC-5C7E23F95CE6.dita"><apiname>ERAMZoneOp_Init</apiname></xref> is

used only once during the initial stages of the system boot process. When

this operation is invoked all the RAM zones that have their bit positions

cleared in the mask pointed to by <codeph>aParam2</codeph> are not currently

in use. The system assumes that during boot all of RAM is enabled and ready

to use. Devices that wish to reduce power consumption can then adjust each

of the RAM IC's partial array self refresh modes or power down modes, appropriately. </p> <p>For

example, if a device has two RAM IC's, IC1 is mapped to zones1-4 and IC2 is

mapped to RAM zones 5-8. Then if the <xref href="GUID-2A00ADB4-778F-3981-A9DC-5C7E23F95CE6.dita"><apiname>ERAMZoneOp_Init</apiname></xref> operation

is requested and all of the RAM zones in RAM IC2 are currently not in use,

then IC2 could be placed into power down mode by the base port at the next

appropriate moment. </p> </li>

</ul> <p>The two parameters, <codeph>aParam1</codeph> =TAny* and <codeph>aParam2</codeph> =const

TAny* allows the call back function to perform multiple operations with the

same interface. When <xref href="GUID-ACA7BAC8-9DC3-356A-92C2-F33A99D8604B.dita"><apiname>TRamZoneCallback</apiname></xref> is called with <xref href="GUID-445BC66E-44AF-3F56-8E8B-CD3C22C0FF8B.dita"><apiname>TRamZoneOp</apiname></xref> defined

as either <xref href="GUID-74DA7B02-CB90-325D-8A84-454004AEB5C8.dita"><apiname>ERamZoneOp_PowerDown</apiname></xref> or <xref href="GUID-3B839FD3-BA8B-38A0-A850-62491C71D3E3.dita"><apiname>ERamZoneOp_PowerUp</apiname></xref>,

the last two parameters are defined as: </p> <ul>

<li id="GUID-19A0CBAC-E630-50E3-9201-6599BAE047E8"><p> <xref href="GUID-037E37E5-B5A1-35B4-B3A8-C36A7C017DE9.dita"><apiname>aParam1</apiname></xref> is

the ID of the RAM zone that changed state </p> </li>

<li id="GUID-DA614AA8-5CCF-59D8-AF81-966FB465A4A3"><p> <xref href="GUID-D07C02D2-C5B2-3D01-B3C5-F24B0D7A9298.dita"><apiname>aParam2</apiname></xref> points

to an array of bit masks that represent the new power state of the RAM zones.

The bit mask is organised in ascending RAM zone address order with the LSB

of the bit mask representing the power state of the lowest addressed zone.

A zone’s bit is set if the RAM zone is in use and cleared if the RAM zone

is not in use. The value of the bit mask <i>MUST</i> not be modified by the

call back function. </p> </li>

</ul> <p>See also: </p> </section>

<section id="GUID-4D506D2E-771F-573F-B5EB-8EA25FAC7C7B"><title>When to reduce

power consumption of the RAM</title> <p>Depending on the RAM IC configuration

for the device, entering and exiting Partial Array Self Refresh (PASR) or

power down modes may introduce a decrease in a device’s overall performance.

The overhead incurred when transitioning a RAM IC from power off to power

on mode may have significant latency due to the amount of initialisation required.

It is recommended that a delay is used between a <xref href="GUID-74DA7B02-CB90-325D-8A84-454004AEB5C8.dita"><apiname>ERamZoneOp_PowerDown</apiname></xref> operation

being invoked and a RAM IC either entering PASR mode or being powered down.

One approach to achieving this is to only enter PASR mode or power down a

RAM IC in the device’s implementation of the <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-473874CA-FC35-3EB2-BC23-A97D7176B833"><apiname>DPowerController::CpuIdle()</apiname></xref> and <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-8AE99718-6B82-3920-9029-28C2041A3B10"><apiname>DPowerController::PowerDown()</apiname></xref> methods.

This way while the device is active its performance is not affected by the

RAM zone operations. </p> </section>

</conbody><related-links>

<link href="GUID-E0DCBDCF-C056-53E5-A375-778327F848E4.dita#GUID-E0DCBDCF-C056-53E5-A375-778327F848E4/GUID-7F5D4AD6-0881-5942-9A86-A95C02125A28">

<linktext>Asic::Init1()</linktext></link>

<link href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita"><linktext>Power Management</linktext>

</link>

<link href="GUID-C13DFF33-7C54-5113-9277-CAD96215F075.dita"><linktext>RAM Zones</linktext>

</link>