<?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_d0e382774_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_d0e382870_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_d0e382925_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-8062EF29-9CE3-5414-9DE2-E494F48F0CFB"><title>Shared power
sources</title> <p>Note: this information applies to Symbian platform before
v9.5. For v9.5 and after, see the <xref href="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita">Power
Resource Manager</xref> documentation. </p> <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>