<?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_d0e376930_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_d0e377026_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_d0e377081_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>