<?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-26621CA5-B686-53FB-AF3E-96CDD38C8520" xml:lang="en"><title> Physical

RAM Defragmentation</title><shortdesc>Describes Symbian platform RAM defragmentation.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Symbian platform physical RAM defragmentation is the process of moving

physical pages, used to back virtual allocations, in order to create empty

physical ranges. This enables the powering off of individual RAM banks or,

if required, the allocation of a large contiguous buffer, for example, for

a CCD image. This functionality allows a more efficient use of RAM in terms

of both memory and power consumption. </p>

<p> <note> Symbian platform RAM defragmentation is used to create large areas

of contiguous RAM and/or allow the powering down of surplus RAM ICs: it does

not locate and consolidate fragmented files and folders. This functionality

enables more efficient use of physical RAM and may enable a lower Bill Of

Materials (BOM), or increase battery life.</note> </p>

<p>There are two interrelated use cases for defragmenting physical RAM: </p>

<ul>

<li id="GUID-51F2B5D3-78B2-5EA3-BEBD-6AB9F21D40BD"><p>many device drivers

require physical RAM for use for buffers. For example, a camera driver may

require a physically contiguous buffer for holding the output of the CCD.

In releases 9.3 and before such memory was typically allocated at boot time.

This practice increases initial RAM consumption after boot. Total RAM consumption

can be reduced if memory for such buffers is only allocated as required, rather

than at boot time. It is not possible to provide an absolute guarantee that

the RAM will be available when needed, but it should succeed in all but exceptional

cases. </p> </li>

<li id="GUID-7865AD99-69C9-511D-9591-1F10A6A62827"><p>typically, memory consumption

of a phone while idle is less than the total memory available. Idle and active

power consumption can be decreased by powering down unused RAM chips or unused

RAM banks within a RAM chip. This may also involve cooperation with a higher

level component in the UI which can shut down unused applications to reclaim

more memory. </p> </li>

</ul>

<section id="GUID-DD63E767-B31C-5311-A4A3-AA6A09B55622"><title>Defragmention

of RAM</title> <p> <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita"><apiname>TRamDefragRequest</apiname></xref> is the class used

by device drivers to perform all defragmentation operations. The three defragmentation

operations provided are: </p> <ul>

<li id="GUID-B8D5E8DA-2E7F-5F08-A86C-FEBB6EAA6011"><p> <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-B4825007-E3DB-3559-9D58-637150EF3DB9"><apiname>TRamDefragRequest::DefragRam()</apiname></xref> –

Performs a general defragmentation. </p> </li>

<li id="GUID-0F001B46-EDB2-551C-8D3D-A1FD51D782FF"><p> <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-8C2CB0BA-6596-3639-90F7-CFEF2D839DB1"><apiname>TRamDefragRequest::ClaimRamZone()</apiname></xref> –

Attempts to claim a whole RAM zone. </p> </li>

<li id="GUID-7E7E62DF-C7F4-5849-A88B-95D7F94F9C75"><p> <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-866259FA-F7D0-360B-AB5D-A1C170383713"><apiname>TRamDefragRequest::EmptyRamZone()</apiname></xref> –

Removes allocated pages from a RAM zone. </p> </li>

</ul> <p>There are three overloads for each of these <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita"><apiname>TRamDefragRequest</apiname></xref> defragmentation

methods which behave differently: </p> <ul>

<li id="GUID-88C45975-36FC-580F-883F-4429FCE0FFC8"><p>The first overload is

synchronous and blocks the calling thread until the defragmentation is complete

(or is cancelled using <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-2903D832-559C-3FE9-9F9F-317DBD28A7E7"><apiname>TRamDefragRequest::Cancel</apiname></xref>). In this

case, the return value is the result of the defragmentation – an appropriate

system-wide error code. </p> </li>

<li id="GUID-5DEFF839-0303-5494-BBCC-04DA3EE8B517"><p>The second overload

is asynchronous and takes a pointer to an <xref href="GUID-22982E51-E746-37CB-9672-97B58C2672BF.dita"><apiname>NFastSemaphore</apiname></xref>.

The semaphore is signalled when the defragmentation is complete. The return

value is <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> unless there was a problem initializing

the request, in which case an appropriate system-wide error code is returned.

The result of the defragmentation can be obtained by calling <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-F3B3F56D-E4D4-3CF5-AE6A-F2607BB4022B"><apiname>TRamDefragRequest::Result()</apiname></xref> after

the semaphore has been signalled. </p> </li>

<li id="GUID-AF7C4053-9317-5B25-B8D9-4B97134969D2"><p>The third overload is

asynchronous and takes a DFC. The DFC is queued when the defragmentation is

complete. The return value is <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> unless there was

a problem initializing the request, in which case an appropriate system-wide

error code is returned. The result of the defragmentation can be obtained

by calling <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-F3B3F56D-E4D4-3CF5-AE6A-F2607BB4022B"><apiname>TRamDefragRequest::Result()</apiname></xref>. </p> </li>

</ul> <p>All <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita"><apiname>TRamDefragRequest</apiname></xref> defragmentation operations

are placed onto a FIFO queue. Any currently running defragmentation operation

must complete or be cancelled before a new defragmentation operation can begin. </p> <p>All

the <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita"><apiname>TRamDefragRequest</apiname></xref> defragmentation methods have the

following parameter in common: </p> <p><b>aPriority </b> </p> <p> <xref href="GUID-80B69100-6D39-3987-B585-522576AA295B.dita"><apiname>aPriority</apiname></xref> specifies the priority

of the thread that performs the defragmentation. If <codeph>aPriority</codeph> = <xref href="GUID-6A6931F2-FC2D-3F8C-8B30-0F17CDBBD2C5.dita"><apiname>KInheritPriority</apiname></xref>,

the default, then the defragmentation thread will execute with the same priority

as thread that invokes the defragmentation operation. </p> <p id="GUID-E514CE19-D643-5447-A3C1-84EDCF84B9C7"><b>Determining the result of

a defragmentation operation</b> </p> <p>For synchronous overloads of the defragmentation

methods the error code returned by the defragmentation method can be used

to determine the result of the defragmentation operation. <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> signifies

that the defragmentation operation was successful. </p> <p>For asynchronous

overloads of the defragmentation methods the result of the defragmentation

operation is determined by invoking <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-F3B3F56D-E4D4-3CF5-AE6A-F2607BB4022B"><apiname>TRamDefragRequest::Result()</apiname></xref> after

it has signalled that it has completed. Again, <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> signifies

that the defragmentation operation was successful. </p> <p id="GUID-19C6DCE9-739F-5085-92FF-626D74F332B1"><b>Cancelling a defragmentation

operation</b> </p> <p>A defragmentation operation can be cancelled by invoking

the <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-EA6C990F-F5B6-3EA6-97A3-F40AAB35351D"><apiname>TRamDefragRequest::Cancel()</apiname></xref> method. This method cancels

the defragmentation, if it is in progress or is in the queue, and causes it

to complete with <xref href="GUID-6F4A88DA-F54E-3848-9C32-942D6F5F4F3E.dita"><apiname>KErrCancel</apiname></xref>. If the defragmentation operation

has already completed, this method has no effect and the result remains as

it was. </p> </section>

<section id="GUID-B4F8543F-538D-5B3A-8F5D-74ACFAAF852F"><title>General defragmentation</title> <p> <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-B4825007-E3DB-3559-9D58-637150EF3DB9"><apiname>TRamDefragRequest::DefragRam()</apiname></xref> initiates a general defragmentation. A general defragmentation attempts

to arrange the currently allocated pages so that only the minimum number and

the most preferable RAM zones required are powered and refreshed. Each time

the general defragmentation successfully empties a RAM zone the base port

invokes the RAM zone call back function with <codeph>aOp = </codeph> <xref href="GUID-74DA7B02-CB90-325D-8A84-454004AEB5C8.dita"><apiname>ERamZoneOp_PowerDown</apiname></xref> see <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>. This informs the base port that it can decide

to, not refresh or power down the empty RAM zone when it deems it to be appropriate. </p> <p>Depending

on the current state of the system and the value of <codeph>aMaxPages</codeph>,

a general defragmentation may require a significant amount of time to complete.

Therefore, if a general defragmentation is performed too frequently the power

saving benefits achieved by powering down or not refreshing RAM zones, may

prove to be less than the power consumed while performing the general defragmentation.

It is recommended that a general defragmentation is only performed once the

device has been idle for a significant period of time. </p> <p><b>aMaxPages </b> </p> <p> <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-B4825007-E3DB-3559-9D58-637150EF3DB9"><apiname> TRamDefragRequest::DefragRam()</apiname></xref> is

similar to the other defragmentation methods, except that it has an additional

parameter <codeph>aMaxPages</codeph>. <codeph>aMaxPages</codeph> specifies

a limit on the number of pages that can be moved during a general defragmentation

when set to zero there is no limit. This can be useful in limiting the amount

of processing a general defragmentation performs and therefore the power consumed

by the general defragmentation. However, setting <codeph>aMaxPages</codeph> too

low may prevent the general defragmentation from being able to empty a single

RAM zone despite there being enough free pages in the most preferable RAM

zones. </p> </section>

<section id="GUID-0BEBEE41-A8DB-56F9-9FCE-E9301CC9864F"><title>RAM defragmentation

of Physically contiguous allocations</title> <p>Some devices may define <xref href="GUID-C13DFF33-7C54-5113-9277-CAD96215F075.dita">RAM Zones</xref> for use

by particular applications or hardware peripherals requiring a block of physically

contiguous RAM. <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-8C2CB0BA-6596-3639-90F7-CFEF2D839DB1"><apiname>TRamDefragRequest::ClaimRamZone()</apiname></xref> is used

by the device driver when it requires use of the pre-determined RAM zone to

be used for the block of physically contiguous RAM. </p> <p> <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-8C2CB0BA-6596-3639-90F7-CFEF2D839DB1"><apiname> TRamDefragRequest::ClaimRamZone()</apiname></xref> is

similar to the other defragmentation methods, except that it has two extra

parameters: </p> <ul>

<li id="GUID-25BF6436-C6F1-5495-B622-D68EE38764C5"><p> <codeph>aId</codeph> –

the ID of the RAM zone to be claimed. </p> </li>

<li id="GUID-B333AD9A-9DEB-5E54-8156-E2FB3587EA9F"><p> <codeph>aPhysAddr</codeph> –

on successful completion of the claim operation this is loaded with the physical

base address of the claimed RAM zone. </p> </li>

</ul> <p>Once a RAM zone has been successfully claimed its memory can be used

by the device driver after being mapped into a <xref href="GUID-51514A4B-0220-557B-9F7A-FB110CEFEF10.dita">shared

chunk</xref>. When the claimed RAM zone is no longer required, the device

driver must use <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-89B28752-7371-3EA8-B213-80F599691D7D"><apiname>Epoc::FreePhysicalRam</apiname></xref> to release it for

use by the rest of the system. </p> </section>

<section id="GUID-91358408-F617-5F0F-B88B-BE9F205AD5FB"><title>Zone specific

allocations</title> <p>A device driver may attempt to allocate memory from

a specific RAM zone using <xref href="GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680.dita#GUID-3DC7B5F2-512E-3FF3-BC08-945DDE2AE680/GUID-43DE887E-9CE0-397E-9AEF-42A051354AE3"><apiname>Epoc::ZoneAllocPhysicalRam()</apiname></xref>.

If the allocation fails then use <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-866259FA-F7D0-360B-AB5D-A1C170383713"><apiname>TRamDefragRequest::EmptyRamZone()</apiname></xref> to

remove as many pages as is reasonable from the RAM zone. </p> <p> <xref href="GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262.dita#GUID-AE7E0A8E-1513-3F6B-A6D5-150084C4E262/GUID-866259FA-F7D0-360B-AB5D-A1C170383713"><apiname> TRamDefragRequest::EmptyRamZone()</apiname></xref> is

similar to the other defragmentation methods, as described in <xref href="GUID-26621CA5-B686-53FB-AF3E-96CDD38C8520.dita#GUID-26621CA5-B686-53FB-AF3E-96CDD38C8520/GUID-DD63E767-B31C-5311-A4A3-AA6A09B55622">Defragmention of RAM</xref>, except that it has an extra parameter: </p> <ul>

<li id="GUID-9C78686E-3AE8-56C0-A7B2-EE2138930935"><p>aId – the ID of the

RAM zone to be emptied. </p> </li>

</ul> <p>Once the empty defragmentation operation has completed the RAM zone

specific allocation can be attempted again. However, the RAM zone specific

allocation may still fail in high RAM usage situations or if the RAM zone

has too many fixed pages allocated. </p> </section>