--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-C376486D-B9BF-5D00-8B1A-1527FC1F83AD.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,193 @@
+<?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>
+</related-links></concept>
\ No newline at end of file