FCL/sftools/depl/docscontent: comparison Adaptation/GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita

equal deleted inserted replaced

-:578be2adaf3e
+:307f4279f433
+<?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-34D1D0BF-20DE-5677-A067-8FF9DD72E703" xml:lang="en"><title>Power Controller DPowerController Implementation Tutorial</title><shortdesc>This topic describes how to implement the <codeph>DPowerController</codeph> class to provide the main power controller functionality in a base
+port.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p><xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita"><apiname>DPowerController</apiname></xref> is defined as: </p>
+<codeblock id="GUID-95318C39-B205-557C-B1F3-75C1441E464A" xml:space="preserve">class DPowerController : public DBase
+{
+public:
+IMPORT_C DPowerController();
+IMPORT_C void Register();
+IMPORT_C void WakeupEvent();
+#ifndef __X86__
+IMPORT_C TInt RegisterResourceController(DBase* aController, TInt aClientId);
+private:
+struct SResourceControllerData
+{
+DBase* iResourceController;
+TInt   iClientId;
+} iResourceControllerData;
+#endif
+public:
+volatile TPowerState    iTargetState;
+public:
+virtual void CpuIdle() = 0;
+virtual void EnableWakeupEvents() = 0;
+virtual void DisableWakeupEvents() = 0;
+virtual void AbsoluteTimerExpired() = 0;
+virtual void PowerDown(TTimeK aWakeupTime) = 0;
+};
+</codeblock>
+<p>The first three functions are exported from the kernel, <filepath>EKERN.EXE</filepath>, while the other five pure virtual functions
+are implemented by your base port. You do not need to export any other
+functions. </p>
+<ul>
+<li id="GUID-2EEFEFF3-FCAF-526C-A11B-790A2A47AA9C"><p> <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita#GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703/GUID-BCCDBA09-415D-5779-BCE5-CDEB2E1EF7D8">Initialising the power controller</xref>, </p> </li>
+<li id="GUID-CBB1EE9C-CD27-5417-973C-3BBED74715D6"><p> <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita#GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703/GUID-DCD91EBA-CB0E-5EA9-84E0-8F8FED6FC91E">DPowerController::RegisterResourceController()</xref>, </p> </li>
+<li id="GUID-4E2D396D-E6FA-5658-830F-9F82D4A63AD1"><p> <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita#GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703/GUID-5A0CAD08-AA12-56EE-B0A3-75548D1896C9">DPowerController::EnableWakeupEvents()</xref>, </p> </li>
+<li id="GUID-DB82BCE3-702A-51EB-ADE0-9434D59CD553"><p> <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita#GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703/GUID-51D37A0C-AD46-52D5-A31C-CB3A8046CE84">DPowerController::AbsoluteTimerExpired()</xref>, </p> </li>
+<li id="GUID-77CCBFFE-037D-5B86-BF14-1BE87D38B47A"><p> <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita#GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703/GUID-1F77C71C-D226-58BB-ABAE-43F958CC0C61">DPowerController::PowerDown()</xref>, </p> </li>
+<li id="GUID-8657D772-2338-588D-B074-832B06144D8B"><p> <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita#GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703/GUID-E2A072D0-A67F-5E6D-81ED-CFD77B6ED4F1">CpuIdle()</xref>. </p> </li>
+</ul>
+<section id="GUID-BCCDBA09-415D-5779-BCE5-CDEB2E1EF7D8"><title>Initialising
+the power controller</title> <p>Typically, you implement your derived
+class in a power management kernel extension, which has the opportunity
+to perform initialisation before the system itself is fully initialised.
+This is done via the extension's DLL entry point. You use the <xref href="GUID-7964FC46-4641-3BDD-92C9-50FA22C3321A.dita"><apiname>DECLARE_STANDARD_EXTENSION()</apiname></xref> macro as a wrapper around
+your initialisation code. There are at least three things to do here: </p> <ul>
+<li id="GUID-25C66F1B-6B2F-5B3B-A827-410263EE22A4"><p>create an instance
+of your power controller object </p> </li>
+<li id="GUID-369A09EC-74D3-529A-AC05-0EFE0C4ABBF7"><p>register your
+power controller object with the Symbian platform power manager, by
+calling <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-F66D72D0-AA27-3BAF-8915-C6E8CC4E7CCF"><apiname>DPowerController::Register()</apiname></xref>. Your power
+controller cannot be used by the Symbian platform power manager until
+it has been registered. </p> </li>
+<li id="GUID-E4C7D934-AAB9-511B-93A4-125D5A5B248D"><p>if you intend
+to use a battery monitor, then you would create it and register it
+as the HAL handler to deal with <xref href="GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7.dita#GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7/GUID-227B4DCD-5D74-3AB7-8E09-64A04D88F094"><apiname>THalFunctionGroup::EHALGroupPower</apiname></xref> calls. See <xref href="GUID-65CDCA83-C726-5173-8E46-B8981D1D7B02.dita">Battery Monitor Implementation Tutorialc</xref> and <xref href="GUID-54042C84-6216-5930-9CBF-BAF635CECD4D.dita">Power HAL Handler
+Tutorial</xref> for more detail. </p> </li>
+</ul> <p>For example: </p> <codeblock id="GUID-1A909C4C-DCAF-54E3-B482-16918E33BF4F" xml:space="preserve">DECLARE_STANDARD_EXTENSION()
+{
+TInt r=KErrNoMemory;
+// Create the power controller object, and register it.
+DPowerController* pC = new DYourPowerController;
+if !(pC)
+{
+return (r);
+}
+pC-&gt;Register();
+// Create the battery monitor.
+DBatteryMonitor* pM = new DYourBatteryMonitor;
+if !(pM)
+{
+return(r);
+}
+r = KErrNone;
+return(r);
+}</codeblock> </section>
+<section id="GUID-DCD91EBA-CB0E-5EA9-84E0-8F8FED6FC91E"><title>DPowerController::RegisterResourceController()</title> <p>The function <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-42896B4D-9F77-3D91-82BD-50102A8F3DA4"><apiname>DPowerController::RegisterResourceController()</apiname></xref> allows the Resource Controller to register itself with the Power
+Controller. See <xref href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita#GUID-66FD040B-133E-57CF-80DD-9369F62709C6/GUID-08BFCAF4-9AF0-5999-A1C4-7BBD107C9354">registering with the resource controller</xref> in the PSL implementation
+document. </p> <p>To support idle power management the Power Controller's
+PSL must override <codeph>RegisterResourceController()</codeph> to
+include the registration of a list of resources whose states are of
+interest to idle power management. </p> <p><b>Idle power management</b> </p> <p>The Power Controller can assemble
+a list of resources whose state it is interested in from a NULL thread
+in an array of <xref href="GUID-586AF75A-8350-345D-ABF4-6542C8E75DED.dita"><apiname>SIdleResourceInfo</apiname></xref> structures. Each
+entry in the list contains the resource ID that the power controller
+must enter before registering with the PRM. The resource list should
+be created in the kernel heap or data section. </p> <p>The example
+below creates a buffer to capture the state of all static resources.
+The PRM captures the information using <xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita#GUID-46F2174F-0206-345B-8C5D-F8B5763652E0/GUID-52DC308A-9DF1-3BDE-A905-A4DD3B692638"><apiname>DPowerResourceController::RegisterResourcesForIdle()</apiname></xref>. </p> <codeblock id="GUID-C6E907FD-094D-5412-8F81-FC02CDE8B411" xml:space="preserve">    ...
+//Allocate buffer for Idle resource management
+NKern::ThreadEnterCS();
+pBuf = HBuf::New(numResources * sizeof(SIdleResourceInfo));
+NKern::ThreadLeaveCS();
+if(!pBuf)
+{
+return KErrNoMemory;
+}
+SIdleResourceInfo* pI = (SIdleResourceInfo*)pBuf-&gt;Ptr();
+//Update resource ID
+for(TUint c = 0; c &lt; numResources; c++)
+{
+pI[c].iResourceId = c+1;
+}
+r = (iResourceControllerData.iResourceController)-&gt;RegisterResourcesForIdle(iResourceControllerData.iClientId, numResources, (TPtr*)pI);
+...</codeblock> <p>The first parameter passed to <codeph>RegisterResourcesForIdle()</codeph> is the client Id generated for the power controller this is the
+client ID passed by the PRM when calling <xref href="GUID-B2C466D1-0B65-3BB7-81B1-7297400E60C4.dita"><apiname>RegisterResourceController</apiname></xref>. </p> <p> <b>Note</b>: <codeph>RegisterResourcesForIdle()</codeph> is not exported and is only available for use by the Power Controller
+to register resources for idle power management. <b>Note</b>: <codeph>RegisterResourcesForIdle()</codeph> can only be called by the Power
+Controller once. </p> </section>
+<section id="GUID-5A0CAD08-AA12-56EE-B0A3-75548D1896C9"><title>DPowerController::EnableWakeupEvents()</title> <codeblock id="GUID-38714507-C38C-5787-997F-5D45F3A90357" xml:space="preserve">virtual void EnableWakeupEvents() = 0;</codeblock> <p>The Symbian Power Model defines 3 generic system-wide <xref href="GUID-113B3755-1797-5D1B-8E07-8A18F5FE1504.dita">power states</xref>: <i>Active</i>, <i>Standby</i> and <i>Off</i>, as defined in the <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita">Symbian platform
+power model</xref>. </p> <p>Each of the system-wide low power states: <i>Standby</i> and <i>Off</i>, has a defined set of wake-up events.
+If a wake-up event occurs while the system is preparing to transition
+into one of these low power states, or when the system is in the <i>Standby</i> state, then this can result in the system moving back
+to the <i>Active</i> power state. Wake-up events may be different
+for different target power states. Wake-up events are platform-specific
+hardware events, and it is your base port that decides which events
+count as wake-up events. </p> <p><b>When is it called?</b> </p> <p> <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-0642129D-05F2-3AB0-B562-37A7BB7A275F"><apiname>DPowerController::EnableWakeupEvents()</apiname></xref> is called called by the <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita#GUID-0C435514-EEC6-5660-BB5F-535790349632/GUID-330F07B2-BBDF-5675-B7D5-FF6B25DD03F4">power manager</xref> as a result of a user side call to <xref href="GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87.dita#GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87/GUID-C49C0A07-EAC7-32CB-956F-1FFEFF2FD326"><apiname>Power::EnableWakeupEvents()</apiname></xref>. The class <xref href="GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87.dita"><apiname>Power</apiname></xref> is the user side interface to the power manager, and is used by
+the user side entity that is responsible for moving the device into
+a low power state. </p> <p><b>Context</b> </p> <p>When the user side entity decides to move
+the device to a low power state, it sends a notification to all of
+the user side power domains registered with it, giving their applications
+a chance to save their data and state. However, before doing this,
+it calls <xref href="GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87.dita#GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87/GUID-C49C0A07-EAC7-32CB-956F-1FFEFF2FD326"><apiname>Power::EnableWakeupEvents()</apiname></xref>. It also calls <xref href="GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87.dita#GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87/GUID-6CFE19D9-249A-3305-8224-823D2FDB1859"><apiname>Power::RequestWakeupEventNotification()</apiname></xref> so that it can
+be informed of a wake-up event. If it is notified of a wake-up event,
+it can halt, and reverse the user side response to the power transition. </p> <fig id="GUID-ACC6E7E3-71E3-5553-B433-9017CB04513D">
+<image href="GUID-AEDBF425-6077-4C84-A698-508291671F2B_d0e27993_href.png" placement="inline"/>
+</fig> <p>Before calling <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-0642129D-05F2-3AB0-B562-37A7BB7A275F"><apiname>DPowerController::EnableWakeupEvents()</apiname></xref>, the power manager sets the <codeph>iTargetState</codeph> member
+of <codeph>DPowerController</codeph> to the applicable <xref href="GUID-87AB8B20-04EE-31D2-8F3D-EA904D05B8D0.dita"><apiname>TPowerState</apiname></xref>. This means that you can enable the appropriate set of wake-up events. </p> <p>Once the user side transition is complete, it calls <xref href="GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87.dita#GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87/GUID-7C6F3F0F-319B-3DEE-81BF-1EB5BB2EAB0A"><apiname>Power::PowerDown()</apiname></xref> in the user side interface to the <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita#GUID-0C435514-EEC6-5660-BB5F-535790349632/GUID-330F07B2-BBDF-5675-B7D5-FF6B25DD03F4">power manager</xref>, which results in a call to <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> in the power controller. This starts the transition of all <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita#GUID-0C435514-EEC6-5660-BB5F-535790349632/GUID-DC5F1ECD-CCA3-59FF-A2F1-A3DBD76CD458">power handlers</xref> to a low power state, a potentially long process.
+This means that the power controller needs the ability to detect wake-up
+events so that it can halt, and reverse the power transition. </p> <p><b>Implementation issues</b> </p> <p>There are three possibilities
+in dealing with wake-up events: </p> <ul>
+<li id="GUID-4243E6DD-C903-58DE-B125-38CEDB8B5269"><p>if wake-up events
+are not handled by specific peripheral drivers, you could set up the
+hardware so that wake-up events are recorded in a location accessible
+by the software. Prior to completing the system power transition,
+the Power controller would check the relevant hardware to see whether
+a wakeup event had occurred. On detecting a wake-up event it would
+tell the power manager by calling <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-C193F898-2C15-3C42-8353-14F00789BCDA"><apiname>DPowerController::WakeupEvent()</apiname></xref>. </p> </li>
+<li id="GUID-289B86C4-A578-5A42-A0DF-70A7BF3F440E"><p>if wake-up events
+are not handled by specific peripheral drivers, you could arrange
+for wake-up events to interrupt the CPU. The code that services those
+interrupts would tell the power manager by calling <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-FABDB7E2-DEC5-3EA9-8106-66C971C04AB7"><apiname>DPowerController::WakepEvent()</apiname></xref>. </p> </li>
+<li id="GUID-E51BAE55-0A81-5D1F-B509-096A7F2141EF"><p>if wakeup events
+are intercepted, serviced and cleared by peripheral drivers, then
+the following outline solution could be adopted: </p> <ul>
+<li id="GUID-5C942237-BBB2-5919-8578-B55BDAFAFC9F"><p>The power controller
+would need to publish a list of wake-up events, preferably as a bit
+mask, and export an API which peripheral drivers could use to notify
+the power controller that a wake-up event has occurred. The following
+interface class could be used for this purpose: </p> <codeblock id="GUID-084F7F46-66B6-5661-85AF-57D499250886" xml:space="preserve">class TPowerController
+{
+public:
+inline static void SetPowerControllerPointer(DPowerController* apPowerController)
+{ iPowerControllerPointer = apPowerController; }
+IMPORT_C static void WakeupEventOccurred(TUint aWakeupEvent);
+…        // other methods if required
+private:
+DPowerController* iPowerControllerPointer;
+};
+</codeblock> <p>The class would be implemented
+as part of the power management kernel extension and <codeph>SetPowerControllerPointer()</codeph> would be called when <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita#GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703/GUID-BCCDBA09-415D-5779-BCE5-CDEB2E1EF7D8">initialising the power controller</xref>, but after creation of the
+power controller object. </p> <p>Those peripheral drivers that intercept
+wake-up events would need to link to the power controller DLL (i.e.
+the power management kernel extension). </p> <p>On the occurrence
+of a wake-up event, the peripheral driver software servicing that
+event would notify the power controller by calling <codeph>WakeupEventOccurred()</codeph>, specifying the appropriate wake-up event bit(s). </p> <p>You might
+implement <codeph>WakeupEventOccurred()</codeph> as follows: </p> <codeblock id="GUID-501ABA28-81B9-52C1-9842-003E1E389045" xml:space="preserve">EXPORT_C void TPowerController::WakeupEventOccurred(TUint aWakeupEvent)
+{
+if(iPowerControllerPointer-&gt;iWakeupEvents &amp; aWakeupEvent)
+{
+iPowerControllerPointer-&gt;WakeupEvent();
+}
+}</codeblock> <p>where <codeph>iWakeupEvents</codeph> is a data
+member defined in your <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita"><apiname>DPowerController</apiname></xref> -derived
+class that contains the bitmask representing the wake-up events. The
+bitmask groups wakeup events according to the target power state. </p> </li>
+</ul> </li>
+</ul> <p>When the peripheral driver powers down, it should leave the
+hardware that generates the wake-up event powered and enabled for
+detection. Thus, if a wake-up event of the type handled by this peripheral
+driver occurs, it will not be serviced in the normal way, but will
+be left pending until the power controller services it. </p> <p>When
+the power controller’s <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> function is called, the power controller must check the peripheral
+hardware directly to see whether the wakeup event has happened, or
+is happening right now, prior to transitioning the device to the target
+system-wide low power state. If the wake-up event is found to have
+happened then <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> would
+return immediately, instead of initiating the <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita#GUID-0C435514-EEC6-5660-BB5F-535790349632/GUID-DC5F1ECD-CCA3-59FF-A2F1-A3DBD76CD458">power handlers</xref> power down of the peripheral drivers. </p> </section>
+<section id="GUID-51D37A0C-AD46-52D5-A31C-CB3A8046CE84"><title> DPowerController::AbsoluteTimerExpired()</title> <codeblock id="GUID-5EC61B73-DA37-51C8-963F-4E4169AC1BE7" xml:space="preserve">virtual void AbsoluteTimerExpired() = 0;</codeblock> <p><b>When is it called?</b> </p> <p> <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-C6F792DB-1EC0-33F4-8F82-AB3F7B44B061"><apiname>DPowerController::AbsoluteTimerExpired()</apiname></xref> is called by the <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita#GUID-0C435514-EEC6-5660-BB5F-535790349632/GUID-330F07B2-BBDF-5675-B7D5-FF6B25DD03F4">power manager</xref> whenever an absolute timer expires. An absolute
+timer is one that is set to complete at a specific time, as queued
+by a call to <xref href="GUID-8A423EA2-4264-30C9-9579-0466994E6E88.dita#GUID-8A423EA2-4264-30C9-9579-0466994E6E88/GUID-3F302410-5CC2-3CCB-82F4-47E953E7A29B"><apiname>RTimer::At()</apiname></xref>. </p> <p><b>Implementation issues</b> </p> <p>If absolute timer expiration
+is one of your wake-up events, then your implementation of <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-C6F792DB-1EC0-33F4-8F82-AB3F7B44B061"><apiname>DPowerController::AbsoluteTimerExpired()</apiname></xref> should call <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-C193F898-2C15-3C42-8353-14F00789BCDA"><apiname>DPowerController::WakeupEvent()</apiname></xref> to notify the power manager
+that a wake-up event has happened. </p> <p>It is recommended that
+you track absolute timers. </p> </section>
+<section id="GUID-1F77C71C-D226-58BB-ABAE-43F958CC0C61"><title>DPowerController::PowerDown()</title> <codeblock id="GUID-AD394AD5-8E3E-5FE3-938E-639C4E5E9F79" xml:space="preserve">virtual void PowerDown(TTimeK aWakeupTime) = 0;</codeblock> <p><b>When is it called?</b> </p> <p> <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> is called by the <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita#GUID-0C435514-EEC6-5660-BB5F-535790349632/GUID-330F07B2-BBDF-5675-B7D5-FF6B25DD03F4">power manager</xref> to move the device into one of the system-wide
+low power states: <i>Standby</i> or <i>Off</i>. </p> <p>Typically,
+this is a result of the user side entity that is responsible for moving
+the device into a low power state calling <xref href="GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87.dita#GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87/GUID-7C6F3F0F-319B-3DEE-81BF-1EB5BB2EAB0A"><apiname>Power::PowerDown()</apiname></xref> in the user side interface to the <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita#GUID-0C435514-EEC6-5660-BB5F-535790349632/GUID-330F07B2-BBDF-5675-B7D5-FF6B25DD03F4">power manager</xref>. </p> <p>If <xref href="GUID-26621CA5-B686-53FB-AF3E-96CDD38C8520.dita">physical RAM defragmentation</xref> is implemented you may wish to include calls to <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> within this function to enable defragmentation of RAM zones that
+can then be powered down. </p> <p><b>Context</b> </p> <p>The target state is defined by the value of
+the <codeph>iTargetState</codeph> member of <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita"><apiname>DPowerController</apiname></xref>, as set by the power manager. </p> <p><b>Implementation issues</b> </p> <p>Implementation depends on the
+target state: </p> <ul>
+<li id="GUID-0473B5C1-BEC0-5276-88C5-A4A8379A4621"><p>if the target
+state is <i>Standby</i>, as implied by a value of <xref href="GUID-87AB8B20-04EE-31D2-8F3D-EA904D05B8D0.dita#GUID-87AB8B20-04EE-31D2-8F3D-EA904D05B8D0/GUID-5604F598-8CBC-3A94-865F-CA58DA4492B0"><apiname>TPowerState::EPwStandby</apiname></xref> in <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-86A0C14F-B219-3E0B-BD5E-A2C20EEDBF64"><apiname>DPowerController::iTargetState</apiname></xref>, then the power
+controller should put the hardware into a state corresponding to the <i>Standby</i> state. </p> <p>If at least one wake-up event has been
+detected and recorded since the last call to <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-0642129D-05F2-3AB0-B562-37A7BB7A275F"><apiname>DPowerController::EnableWakeupEvents()</apiname></xref>, then <codeph>PowerDown()</codeph> should return immediately; otherwise,
+it should continue with the process of putting the device into <i>Standby</i>; execution of the function will halt, and can only continue,
+and return, when a wake-up event occurs. </p> </li>
+<li id="GUID-E38B9334-CFE4-5E91-9DD4-D7A0678AF344"><p>if the target
+state is <i>Off</i>, as implied by a value of <xref href="GUID-87AB8B20-04EE-31D2-8F3D-EA904D05B8D0.dita#GUID-87AB8B20-04EE-31D2-8F3D-EA904D05B8D0/GUID-0DAD6E93-BD08-3C90-BCE8-ADBFC2681227"><apiname>TPowerState::EPwOff</apiname></xref> in <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-86A0C14F-B219-3E0B-BD5E-A2C20EEDBF64"><apiname>DPowerController::iTargetState</apiname></xref>, then <codeph>PowerDown()</codeph> must <i>never</i> return. Typically, the power
+controller turns the device off, but can choose to perform other device-specific
+action such as a system reboot. </p> </li>
+</ul> <p>The <xref href="GUID-8C6E2996-24DE-3E59-927A-46D32290225E.dita"><apiname>TTimeK</apiname></xref> parameter passed to the function
+is a system time value. If non-zero, it specifies the time when the
+system should wakeup. The kernel calculates it as the time that the
+next absolute timer expires. Typically, your implementation will use
+the Real Time Clock module to generate an event at the specified time,
+and this will cause a return to the <i>Active</i> state. This implies
+that the base port should enable Real Time Clock event detection during <i>Standby</i>. </p> <p>The Symbian definition of the <i>Standby</i> state usually translates into the hardware manufacturer’s CPU “Standby”
+or “Sleep” modes of operation. Typically, the internal clocks associated
+with the core and some of the core peripherals, or their power supply,
+are suppressed, and their internal state is not preserved. In this
+case, the state of the core and core peripherals should be saved before
+going into <i>Standby</i> so that they can be restored when the system
+wakes-up. Note the following: </p> <ul>
+<li id="GUID-824D88FD-33FB-50DC-A904-F5F44BFBF90A"><p>for the core
+state, save the current mode, the banked registers for each mode,
+and the stack pointer for both the current mode and user mode </p> </li>
+<li id="GUID-E8CDFA98-E6F2-5D48-987F-E2591DAB242B"><p>for the core
+peripherals, save the state of the interrupt controller, the pin function
+controller, the bus state controller, and the clock controller </p> </li>
+<li id="GUID-90BEA663-F58C-5AD7-8578-353E5EFFBCCC"><p>for the MMU
+state, save the control register, the translation table base address,
+and the domain access control, if this is supported </p> </li>
+<li id="GUID-68AB9558-5CC7-573F-8A33-A38F16EAF304"><p>flush the data
+cache and drain the write buffer. </p> </li>
+</ul> <p>If all of this data is saved to a DRAM device, then this
+should be put into self refresh mode. </p> <p>Peripherals modules
+involved in the detection of wake-up events should be left powered. </p> <p>Tick timer events should be disabled, and the current count of
+this and any other system timers should be saved; relevant wake-up
+events should be left unmasked, and any others should be disabled. </p> </section>
+<section id="GUID-E2A072D0-A67F-5E6D-81ED-CFD77B6ED4F1"><title>DPowerController::CpuIdle()</title> <codeblock id="GUID-0E6F1B1D-F979-575B-BA3C-096CE4C0CA15" xml:space="preserve">virtual void CpuIdle()=0;</codeblock> <p><b>When is it called?</b> </p> <p> <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> is called whenever the Null thread is scheduled to run. This can
+happen as soon as the power model has been installed. It is the mechanism
+through which your base port can increase power savings when the system
+becomes inactive by moving the CPU or the system into a low power
+mode. </p> <p>If <xref href="GUID-26621CA5-B686-53FB-AF3E-96CDD38C8520.dita">physical RAM defragmentation</xref> is implemented you may wish to
+include calls to <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> within this function to enable defragmentation while the device
+is idle. </p> <p><b>Implementation issues</b> </p> <p>The implementation can call
+the Variant or ASSP implementation of <xref href="GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D.dita#GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D/GUID-6F242C0C-2EFC-30EC-9A5E-A34C8D15E0D7"><apiname>Asic::Idle()</apiname></xref>. </p> <p>The idle state is usually implemented via a Wait-For-Interrupt
+type instruction that will usually suspend execution of the CPU, possibly
+triggering other ASIC power saving actions, and will resume execution
+when any unmasked interrupt occurs. </p> <p><b>Suppressing the system tick interrupt</b> </p> <p>To further increase
+power savings during CPU Idle, a base port can choose to suppress
+the system tick interrupt until the next nanokernel Timer (as implemented
+by <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref>) is due to expire. Nanokernel timers
+are the basic timing service and all Symbian platform tick-based timers
+and time-of-day functions are derived from nanokernel timers. </p> <p>In EKA2, timing services rely on a hardware timer, which is programmed
+by the base port Variant code, to generate the system tick. We refer
+to this as the <i>system timer</i>. </p> <p>Typically, the platform-specific
+ASSP or Variant object has a pointer to the nanokernel timer queue,
+an <xref href="GUID-C54D99AA-FF6E-3023-8260-8F5A88FBFBE0.dita"><apiname>NTimerQ</apiname></xref> object. The number of ticks before the
+next <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref> is due to expire can be found by calling <xref href="GUID-C54D99AA-FF6E-3023-8260-8F5A88FBFBE0.dita#GUID-C54D99AA-FF6E-3023-8260-8F5A88FBFBE0/GUID-69103F26-2C21-3ECA-9DB5-C31A41F6C238"><apiname>NTimerQ::IdleTime()</apiname></xref>. </p> <p>Before going into Idle mode, <codeph>CpuIdle()</codeph> disables the hardware timer used to generate the
+system tick (i.e. the system timer) for the number of ticks to be
+suppressed; i.e. the system timer is reset to go off and generate
+an interrupt only when the <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref> expires. Note
+that the clock supply to the hardware timer must be left enabled. </p> <p>On returning from Idle mode, the software must examine the system
+timer and decide whether the <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref> expiration
+was responsible for waking up the processor, or whether it was due
+to some other interrupt. </p> <p>If waking up was due to the <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref>, the system timer must be reset to generate the
+system tick at the frequency desired, and the tick count, <xref href="GUID-C54D99AA-FF6E-3023-8260-8F5A88FBFBE0.dita#GUID-C54D99AA-FF6E-3023-8260-8F5A88FBFBE0/GUID-ACFDFE7C-19AE-3C81-9D38-3266A3A3EF1F"><apiname>NTimerQ::iMsCount</apiname></xref>, must be adjusted with the <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref> expiration time. As the expiration time is always an integer multiple
+of the number of ticks, then the <xref href="GUID-C54D99AA-FF6E-3023-8260-8F5A88FBFBE0.dita#GUID-C54D99AA-FF6E-3023-8260-8F5A88FBFBE0/GUID-AA1EC86F-8A6E-340D-848F-A86554772A13"><apiname>NTimerQ::Advance()</apiname></xref> function can be used for this purpose. </p> <p>If waking up was
+due to another interrupt, then the software must read the system timer
+and calculate the time elapsed since going into Idle mode, and adjust
+the system tick count with the elapsed time (which could be a fractional
+number of ticks) and reprogram the system timer to continue generating
+the tick after the correct interval, as above. </p> <p>If the hardware
+timer that is used to generate the system ticks does not use a Compare-Match
+function, then some care has to be taken not to introduce skewing
+when manipulating the timer value directly. If the timer needs to
+be reloaded with the new value to give the next tick, then the software
+usually “spins”, waiting for the hardware timer to change, and then
+reloads it. This way the timer will always be reloaded on an edge
+of its internal clock. </p> <p><b>Waking up from “Sleep” modes with long wakeup latencies</b> </p> <p>Often, to further enhance power savings, the CPU and some peripherals
+are moved into a hardware “sleep” mode when <codeph>CpuIdle()</codeph> is called. This could be of long latency, and waking up could take
+longer than the system Tick period. There are two situations: </p> <ul>
+<li id="GUID-7484F7CB-C824-5752-9043-736E95D4405D"><p>if the wakeup
+time can be determined precisely, then <codeph>CpuIdle()</codeph> programs
+the system timer to bring the CPU back from the “Sleep“ mode at a
+time corresponding to the next <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref> expiration
+(as a number of Ticks to suppress) <i>minus</i> the number of ticks
+it takes to wake up from that mode. On waking up on the timer, the
+System tick count should be adjusted with the total number of ticks
+suppressed, i.e. the count corresponding to the time of the <xref href="GUID-D8CF05A3-5C9B-3662-92DA-3290C6EE7FD2.dita"><apiname>NTimer</apiname></xref> expiration. </p> </li>
+<li id="GUID-C0A9B2A2-D98D-50C0-B58A-4E84FCEC12E4"><p>If the wakeup
+time cannot be known deterministically, then the above scheme must
+be combined with another system to allow adjusting the system timer
+from the hardware Real Time Clock (RTC). </p> <p>Typically, the hardware
+RTC is clocked with a 1Hz clock, and can be programmed to interrupt
+the CPU on multiples of one second intervals. The clock supply to
+the RTC must be left enabled on going into "sleep" mode. </p> </li>
+</ul> <p>To guarantee that timed events occur when they are due, the
+CPU should only be allowed to go to into the long latency hardware
+“sleep” mode if the RTC can be guaranteed to complete a second tick
+before the CPU is due to wakeup. </p> <p>Note that if waking up from
+hardware “Sleep” mode takes a non-negligible amount of time, extreme
+care should be taken when deciding to move the platform into that
+mode. For example, if a receive request is pending on a data input
+device <i>and</i> the CPU reaches the Idle mode <i>and</i> the platform
+is transitioned into a “sleep” state <i>and</i> data arrives while
+it is still in that state, <i>then</i> there is a possibility that
+the system will not wake up on time to service the incoming data. </p> </section>
+<section id="GUID-4B613C67-3A12-4AD5-8842-6ED510A68746"><title>Validation</title> <p>The <filepath>e32test</filepath> programs <filepath>t_power</filepath>, and <filepath>t_timer</filepath> will put the system into standby
+and resume off a timer. </p> </section>
+</conbody><related-links>
+<link href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita"><linktext>Power
+Management</linktext></link>
+</related-links></concept>