<?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-0C435514-EEC6-5660-BB5F-535790349632" xml:lang="en"><title>Power Management</title><shortdesc>The kernel provides a framework for managing power within
the system, and the management of the transition between power states. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The kernel-side framework manages the transition between power
states on the device. A base port can implement a kernel extension
to interface to the power management hardware that is provided on
the phone. The framework also provides an interface for device drivers
to use the power </p>
<p>The user-side interface to the framework is provided by the Power
class in the User Library. This allows applications can be notified
about, and can react to, changes in power state, and indeed can initiate
changes to power state. The <xref href="GUID-E09E4418-4DC3-56A3-BFBE-486C9C8D25C9.dita">Domain Manager</xref> component provides a way to manage the power needs and dependencies
of applications. </p>
<p>In Symbian platform, an initial port of the system does not require
the existence of a power model. In this sense it is optional, and
its absence will result in default behaviour provided by Symbian platform.
However, this is not likely to result in optimal power usage, so the
development of a power model based on the framework provided by Symbian
platform will be required for commercial devices. </p>
<p>The interfaces for power management on the kernel-side are shown
in the following diagram: </p>
<fig id="GUID-4020768D-7FDF-58EC-82A7-F98E259046D0">
<image href="GUID-782E8D92-0431-50F5-95A0-5B231EBDF391_d0e25767_href.png" placement="inline"/>
</fig>
<ul>
<li id="GUID-4E59C261-2025-5402-9EE1-EBC50BCD409F"><p>The power manager
manages the transition between power states. </p> </li>
<li id="GUID-B3CD4688-45D0-5F46-A968-2DDD76ABB9B7"><p>The power controller
is a kernel extension that manages the device-specific power management
hardware such as an on-chip power management controller, oscillators
etc. The power controller kernel extension is provided in the base
port. </p> </li>
<li id="GUID-07CBC9E9-7A2E-5BB5-95F6-1ECF36B502ED"><p>Power handlers
are device drivers that interface to the power manager. </p> </li>
</ul>
<p>The following sections describes these concepts in more detail. </p>
<section id="GUID-330F07B2-BBDF-5675-B7D5-FF6B25DD03F4"><title>Power
manager</title> <p>The power manager manages the transition between
power states. It co-ordinates the change in the power state of peripherals
and the CPU (hardware), and provides the necessary interactions with
the device (peripheral) drivers and the power controller (software).
It also manages interactions with the user-side model. </p> <p>The
power manager is an instance of the <codeph>DPowerManager</codeph> class, an object that is private to Symbian platform. This object
is created when the system is initialised, but is not installed as
the power manager until the <xref href="GUID-0C435514-EEC6-5660-BB5F-535790349632.dita#GUID-0C435514-EEC6-5660-BB5F-535790349632/GUID-07F53484-4727-5338-9320-DF6A0BB440E4">power controller</xref> has been created and registered. Until the <codeph>DPowerManager</codeph> object is installed as the system's power
manager, Symbian platform manages power using built-in default behaviour. </p> <p>The user-side uses the <xref href="GUID-15D25C07-CFD2-32CE-AD22-E17D512D8E87.dita"><apiname>Power</apiname></xref> class, a set
of static functions, as an interface to the power manager. This allows
the user side to request a transition to the <i>Standby</i> or <i>Off </i> state, and to request notification of wake-up events, i.e.
events that will cause a transition back to the <i>Active</i> state. </p> <p>The power manager object is the anchor point for the power controller
object and the power handler objects. </p> </section>
<section id="GUID-07F53484-4727-5338-9320-DF6A0BB440E4"><title>Power
controller</title> <p>The power controller manages the device-specific
power management hardware such as an on-chip power management controller,
oscillators etc. </p> <p>The power controller is an instance of a <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita"><apiname>DPowerController</apiname></xref> class. This is an abstract class that
requires an implementation . A concrete implementation supports power
management hardware that is Variant specific. Typically, the Variant
creates a power controller object when the Variant is initialised,
and then registers it with the power manager through a call to <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>. Registration puts a pointer
to the <codeph>DPowerController</codeph> object into the Symbian platform
internal <codeph>DPowerManager</codeph> object. </p> <p>The power
controller is responsible for tracking wake-up events, notifying the
power manager of such events through a call to <xref href="GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366.dita#GUID-B3D1C422-6A82-3C6E-9123-1E4F598F0366/GUID-3524A807-F4A9-3DE4-918A-0C03BE0D1AEF"><apiname>DPowerController::WakeUpEvent()</apiname></xref>. </p> <fig id="GUID-7BBCE70B-381C-5E65-83CF-498B2C6D15DA">
<image href="GUID-9D8C62FB-1E42-5B69-8ECC-2B68AD7C71A5_d0e25863_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-DC5F1ECD-CCA3-59FF-A2F1-A3DBD76CD458"><title>Power
handlers</title> <p>Device drivers interface to the power manager
through the <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref> class. This is an abstract
class that requires a concrete implementation by device (peripheral)
drivers. </p> <p>How a <codeph>DPowerHandler</codeph> object fits
into a driver's own object model is a matter of individual device
driver design. However, after construction of this object, the driver
is expected to register it with the power manager by calling <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-E8353DF6-B21B-383F-99AB-94B6B5139E47"><apiname>DPowerHandler::Add()</apiname></xref>, after which it will receive notification
of changes to the power state. </p> <p>The power manager calls <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-578DB5FB-731D-36B2-A459-AAC7F250D726"><apiname>DPowerHandler::PowerDown()</apiname></xref> when it requests a power state
transition to either the <i>Off</i> or the <i>Standby</i> state. The
power manager calls <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-DDC564B4-BD12-30E9-B04A-DBA6CFAF8743"><apiname>DPowerHandler::PowerUp()</apiname></xref> when
it requests a power state transition to the <i>Active</i> state. The
driver must respond to a power transition notification after it has
dealt with it by calling <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-BF62042B-FB7B-3D5B-8379-490FBA284A7A"><apiname>DPowerHandler::PowerUpDone()</apiname></xref> or <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita#GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7/GUID-EBE8CFF8-50BD-3AC3-A4C8-47094DA5674D"><apiname>DPowerHandler::PowerDownDone()</apiname></xref> as appropriate. </p> <fig id="GUID-5A5E8846-DE8A-50FC-9D0E-8D8E88291835">
<image href="GUID-1BB379B6-C0B5-5099-90A0-1BA39DC2C7DD_d0e25918_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-8062EF29-9CE3-5414-9DE2-E494F48F0CFB"><title>Shared
power sources</title> <note><p>See the <xref href="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita">Power Resource Manager</xref> documentation for more information. </p></note> <p>The set of power sources on a device, how they are connected to peripherals,
and their power states are totally dependent on the specific device.
This means that Symbian platform cannot provide a comprehensive API
for handling such sources. </p> <p>However, Symbian platform does
provide an interface, <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita"><apiname>MPowerInput</apiname></xref>, through which
drivers register their use of a power source and their release of
that power source. Symbian platform makes the following recommendations: </p> <ul>
<li id="GUID-D1B32CB8-E3EF-532C-9771-D5B9CFE3C5DD"><p>Each (shared)
power source is represented by a separate object. </p> </li>
<li id="GUID-AA47D3A2-8F3A-5D7D-AB41-8658FF5C9260"><p>The class, or
class hierarchy, that represents the power source should implement
the <codeph>MPowerInput</codeph> interface so that device (peripheral)
drivers can register their use or their release of that power source. </p> </li>
<li id="GUID-017BC38F-1207-52B8-8B35-D38F66849FC6"><p>Define a custom
interface with the power controller. It is likely that the Variant
will be responsible for providing the implementation for the power
inputs, and for providing this custom interface. </p> </li>
</ul> <p>Drivers that need power from a specific power source call <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita#GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A/GUID-2BCA5312-43D9-3763-9636-3B2EB046D2C1"><apiname>MPowerInput::Use()</apiname></xref> on the object that represents that power
source. To release dependence on that power source, the driver calls <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita#GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A/GUID-606ECD77-A5F7-3408-9B63-C68C0A7B73C6"><apiname>MPowerInput::Release()</apiname></xref>. </p> <p>To represent a shared power
source, a suggested implementation of <codeph>MPowerInput</codeph> might be to associate a counting value with the power source object.
A call to <codeph>Use()</codeph> would increment the counter, while
a call to <codeph>Release()</codeph> would decrement it. On construction
of the object, the initial value might be 0, indicating that no peripherals
require power from this source. A value of 1 or higher would indicate
that one or more peripherals require power from this source. The implementation
would, therefore, cause this power source to be kept on while at least
one peripheral needs it; the power source would only be switched off
when no peripherals need power from it. </p> </section>
</conbody><related-links>
<link href="GUID-E09E4418-4DC3-56A3-BFBE-486C9C8D25C9.dita"><linktext>Domain
Manager</linktext></link>
<link href="GUID-3773A78D-F491-52EB-AA1D-201636497F28.dita"><linktext>Power
Management Tutorials</linktext></link>
<link href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita"><linktext>Power
Resource Manager (PRM)</linktext></link>
</related-links></concept>