|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <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 |
|
13 the system, and the management of the transition between power states. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The kernel-side framework manages the transition between power |
|
15 states on the device. A base port can implement a kernel extension |
|
16 to interface to the power management hardware that is provided on |
|
17 the phone. The framework also provides an interface for device drivers |
|
18 to use the power </p> |
|
19 <p>The user-side interface to the framework is provided by the Power |
|
20 class in the User Library. This allows applications can be notified |
|
21 about, and can react to, changes in power state, and indeed can initiate |
|
22 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 |
|
23 of applications. </p> |
|
24 <p>In Symbian platform, an initial port of the system does not require |
|
25 the existence of a power model. In this sense it is optional, and |
|
26 its absence will result in default behaviour provided by Symbian platform. |
|
27 However, this is not likely to result in optimal power usage, so the |
|
28 development of a power model based on the framework provided by Symbian |
|
29 platform will be required for commercial devices. </p> |
|
30 <p>The interfaces for power management on the kernel-side are shown |
|
31 in the following diagram: </p> |
|
32 <fig id="GUID-4020768D-7FDF-58EC-82A7-F98E259046D0"> |
|
33 <image href="GUID-782E8D92-0431-50F5-95A0-5B231EBDF391_d0e25767_href.png" placement="inline"/> |
|
34 </fig> |
|
35 <ul> |
|
36 <li id="GUID-4E59C261-2025-5402-9EE1-EBC50BCD409F"><p>The power manager |
|
37 manages the transition between power states. </p> </li> |
|
38 <li id="GUID-B3CD4688-45D0-5F46-A968-2DDD76ABB9B7"><p>The power controller |
|
39 is a kernel extension that manages the device-specific power management |
|
40 hardware such as an on-chip power management controller, oscillators |
|
41 etc. The power controller kernel extension is provided in the base |
|
42 port. </p> </li> |
|
43 <li id="GUID-07CBC9E9-7A2E-5BB5-95F6-1ECF36B502ED"><p>Power handlers |
|
44 are device drivers that interface to the power manager. </p> </li> |
|
45 </ul> |
|
46 <p>The following sections describes these concepts in more detail. </p> |
|
47 <section id="GUID-330F07B2-BBDF-5675-B7D5-FF6B25DD03F4"><title>Power |
|
48 manager</title> <p>The power manager manages the transition between |
|
49 power states. It co-ordinates the change in the power state of peripherals |
|
50 and the CPU (hardware), and provides the necessary interactions with |
|
51 the device (peripheral) drivers and the power controller (software). |
|
52 It also manages interactions with the user-side model. </p> <p>The |
|
53 power manager is an instance of the <codeph>DPowerManager</codeph> class, an object that is private to Symbian platform. This object |
|
54 is created when the system is initialised, but is not installed as |
|
55 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 |
|
56 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 |
|
57 of static functions, as an interface to the power manager. This allows |
|
58 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. |
|
59 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 |
|
60 object and the power handler objects. </p> </section> |
|
61 <section id="GUID-07F53484-4727-5338-9320-DF6A0BB440E4"><title>Power |
|
62 controller</title> <p>The power controller manages the device-specific |
|
63 power management hardware such as an on-chip power management controller, |
|
64 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 |
|
65 requires an implementation . A concrete implementation supports power |
|
66 management hardware that is Variant specific. Typically, the Variant |
|
67 creates a power controller object when the Variant is initialised, |
|
68 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 |
|
69 to the <codeph>DPowerController</codeph> object into the Symbian platform |
|
70 internal <codeph>DPowerManager</codeph> object. </p> <p>The power |
|
71 controller is responsible for tracking wake-up events, notifying the |
|
72 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"> |
|
73 <image href="GUID-9D8C62FB-1E42-5B69-8ECC-2B68AD7C71A5_d0e25863_href.png" placement="inline"/> |
|
74 </fig> </section> |
|
75 <section id="GUID-DC5F1ECD-CCA3-59FF-A2F1-A3DBD76CD458"><title>Power |
|
76 handlers</title> <p>Device drivers interface to the power manager |
|
77 through the <xref href="GUID-761AE02B-41A6-35EA-AA9F-0AEEFF67A6F7.dita"><apiname>DPowerHandler</apiname></xref> class. This is an abstract |
|
78 class that requires a concrete implementation by device (peripheral) |
|
79 drivers. </p> <p>How a <codeph>DPowerHandler</codeph> object fits |
|
80 into a driver's own object model is a matter of individual device |
|
81 driver design. However, after construction of this object, the driver |
|
82 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 |
|
83 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 |
|
84 transition to either the <i>Off</i> or the <i>Standby</i> state. The |
|
85 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 |
|
86 it requests a power state transition to the <i>Active</i> state. The |
|
87 driver must respond to a power transition notification after it has |
|
88 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"> |
|
89 <image href="GUID-1BB379B6-C0B5-5099-90A0-1BA39DC2C7DD_d0e25918_href.png" placement="inline"/> |
|
90 </fig> </section> |
|
91 <section id="GUID-8062EF29-9CE3-5414-9DE2-E494F48F0CFB"><title>Shared |
|
92 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, |
|
93 and their power states are totally dependent on the specific device. |
|
94 This means that Symbian platform cannot provide a comprehensive API |
|
95 for handling such sources. </p> <p>However, Symbian platform does |
|
96 provide an interface, <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita"><apiname>MPowerInput</apiname></xref>, through which |
|
97 drivers register their use of a power source and their release of |
|
98 that power source. Symbian platform makes the following recommendations: </p> <ul> |
|
99 <li id="GUID-D1B32CB8-E3EF-532C-9771-D5B9CFE3C5DD"><p>Each (shared) |
|
100 power source is represented by a separate object. </p> </li> |
|
101 <li id="GUID-AA47D3A2-8F3A-5D7D-AB41-8658FF5C9260"><p>The class, or |
|
102 class hierarchy, that represents the power source should implement |
|
103 the <codeph>MPowerInput</codeph> interface so that device (peripheral) |
|
104 drivers can register their use or their release of that power source. </p> </li> |
|
105 <li id="GUID-017BC38F-1207-52B8-8B35-D38F66849FC6"><p>Define a custom |
|
106 interface with the power controller. It is likely that the Variant |
|
107 will be responsible for providing the implementation for the power |
|
108 inputs, and for providing this custom interface. </p> </li> |
|
109 </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 |
|
110 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 |
|
111 source, a suggested implementation of <codeph>MPowerInput</codeph> might be to associate a counting value with the power source object. |
|
112 A call to <codeph>Use()</codeph> would increment the counter, while |
|
113 a call to <codeph>Release()</codeph> would decrement it. On construction |
|
114 of the object, the initial value might be 0, indicating that no peripherals |
|
115 require power from this source. A value of 1 or higher would indicate |
|
116 that one or more peripherals require power from this source. The implementation |
|
117 would, therefore, cause this power source to be kept on while at least |
|
118 one peripheral needs it; the power source would only be switched off |
|
119 when no peripherals need power from it. </p> </section> |
|
120 </conbody><related-links> |
|
121 <link href="GUID-E09E4418-4DC3-56A3-BFBE-486C9C8D25C9.dita"><linktext>Domain |
|
122 Manager</linktext></link> |
|
123 <link href="GUID-3773A78D-F491-52EB-AA1D-201636497F28.dita"><linktext>Power |
|
124 Management Tutorials</linktext></link> |
|
125 <link href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita"><linktext>Power |
|
126 Resource Manager (PRM)</linktext></link> |
|
127 </related-links></concept> |