<?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>