<?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-2ECF13A1-9D56-5740-A09F-8267E6A45DD9" xml:lang="en"><title>Porting the Power Resource Manager</title><shortdesc>This tutorial describes how to port the Platform Specific

Layer (PSL) of the Power Resource Manager (<keyword>PRM</keyword>)

and how to modify clients, such as device drivers, to use the PRM

framework.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-97905214-40EC-44A1-95D6-7F2C1636C638"><title>Purpose</title> <p>The PRM is a framework for managing system power resources. This

framework improves portability across different platforms and reduces

device driver complexity. </p> <p>The PRM framework is split into

two layers: </p> <ul>

<li id="GUID-17F4DFA5-2848-5CA9-BE5D-F7F52BB1705F"><p>Platform Independent

Layer - the PIL is a generic software layer that is implemented by

Symbian. This is the base virtual class for the Power Resource Controller

(<xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita"><apiname>DPowerResourceController</apiname></xref>), </p> </li>

<li id="GUID-B6499506-0B33-588F-BEFC-12A4D9FDF239"><p>Platform Specific

Layer - the PSL is developed specifically to interface with the target

hardware by licensees. This is the class derived from <codeph>DPowerResourceController</codeph>. </p> </li>

</ul> <p>Other acronyms used in this document set: </p> <ul>

<li id="GUID-ED8A465C-B8CB-5C7A-8D57-D207AAA41F89"><p>H4 HRP - OMAP2420

SDP hardware reference platform referred to in these documents as

examples of the base port, </p> </li>

<li id="GUID-97B58DBF-51DA-5982-A2D2-BF3453B062F2"><p>LDD - Logical

Device Driver. The higher layer of abstraction within the Symbian

platform device driver framework which implements common functionality

among differing pieces of hardware of one type, </p> </li>

<li id="GUID-547FA744-0D75-516A-954A-E9D1DBCBAC87"><p>PDD - Physical

Device Driver. The lower layer of abstraction within the Symbian platform

device driver framework which implements functionality that is specific

to a particular piece of hardware. </p> </li>

</ul> <p><b>Intended audience</b> </p> <p>This document is intended

to be used by Symbian platform device creators. </p> <p><b>Required

background</b> </p> <p>The reader of this document is assumed to have

knowledge of the Symbian platform device driver model and <keyword>base port</keyword> layering and components. </p> <ul>

<li id="GUID-611721D2-17C4-56F4-9101-6088B062BB2C"><p> <xref href="GUID-8D80AA51-5108-5D4B-B6B9-7FA47570AB89.dita">Device Driver Concepts</xref>, </p> </li>

<li id="GUID-938A492F-B9CB-5DFB-B382-2B7E6C5E3711"><p> <xref href="GUID-A7F6C8D5-B85B-537B-8A19-99149FBE8C01.dita">The core porting

process</xref>. </p> </li>

</ul> <p>This document refers to the reference implementation of the

PRM PSL for the H4 HRP platform wherever possible. The source code

for the reference implementation can be found in <filepath>\omap_hrp\h4\resman</filepath>. The MMC and Sound_SC (in H4 HRP) device drivers are modified to

use the new PRM framework. </p> <p><b>Introduction</b> </p> <p>The

PRM provides a unique place where all the current power states for

resources can be obtained at any time. The sum of all internal and

external power states defines the current system-wide power state. </p> <p id="GUID-0F328055-DBCE-5B2B-A1EB-77F73BA1FC82"><b>Setup and configuration

requirements</b> </p> <p>The PRM component is implemented as a kernel

extension with an exported public interface that is accessible to

kernel side components through statically linking against its export

library. The export library is built from the resource manager and

the resource manager libraries. </p> <p>There are two versions available: </p> <ul>

<li id="GUID-982137EB-A7C2-5420-8279-477AC52D5350"><p>basic resource

manager - provides essential or required functionality for static

resources. </p> <p>The basic version of the PIL layer is compiled

into <filepath>resmanpsl.lib</filepath>. This kernel library must

be included by the PSL to produce the kernel extension. </p> </li>

<li id="GUID-0F8863B3-044C-5B5A-831D-DB20B72459C8"><p>extended resource

manager - provides additional support for dynamic resources and resource

dependencies. </p> <p>The extended version of the PIL layer is complied

into <filepath>resmanextenedpsl.lib</filepath>. This kernel library

must be included by the PSL to produce the kernel extension. </p> </li>

</ul> <p>Device drivers that require the use of the PRM should link

against the appropriate library. <filepath>resman.lib</filepath> to

use the basic version and <filepath>resmanextended.lib</filepath> to

use the extended version of the PRM. </p> <p><b>Building the PRM for

the target platform</b> </p> <p>The PRM is an early extension, so

the <codeph>targettype</codeph> in the <keyword>mmp</keyword> file

must be set to <codeph>kext</codeph>. If the PRM is implemented as

a PDD the <codeph>targettype</codeph> in the mmp file should be should

be <codeph>pdd</codeph>. </p> <p><b>Boot sequence</b> </p> <p>The PRM cannot be used to operate on power resources until

later in the boot sequence when the kernel allows the scheduling of

other threads. During this time it is not possible to read or change

the state of resources, but <xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita#GUID-46F2174F-0206-345B-8C5D-F8B5763652E0/GUID-9D07A9C1-C0AE-36E9-8438-3BF71D3CBB0C"><apiname>DPowerResourceController::PostBootLevel()</apiname></xref> can be used to specify the state of specific resources and the PRM

can change the state of resources to appropriate levels before the

PRM is fully initialised. </p> <p> <codeph>PostBootLevel()</codeph> is used within the extension entry point, during this time PRM is

not fully initialised. <b>Note</b>: This function can only be used

for static resources and static resources with dependencies. </p> <codeblock id="GUID-F8E2125A-0DA8-5991-8FED-BF6DA48EC79D" xml:space="preserve">static TInt PostBootLevel(TUint aResId, TInt aLevel);</codeblock> <p> <codeph>PostBootLevel()</codeph> takes the resource ID and the

post boot level that the level a resource needs to be after it is

initialised. Typically the post boot level is only known to the PSL.

However kernel extensions (and the variant) may request a post boot

level. </p> <p>If a kernel extension needs to know if certain resources

have reached the post boot state in order to complete its own initialisation

then the kernel extension should queue resource state change notifications

for the resource when first registering as clients with the PRM. <b>Note</b>: notification requests are accepted before the PRM is fully

initialised. </p> <p>Variants or kernel extensions can register static

resources before the PRM is fully initialised with <xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita#GUID-46F2174F-0206-345B-8C5D-F8B5763652E0/GUID-6F74C10F-5055-37D2-968D-FCAB7D0F8FDF"><apiname>DPowerResourceController::RegisterStaticResource()</apiname></xref>. This API can only be used by static resources and not by static

resource that support dependency. See <xref href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita#GUID-66FD040B-133E-57CF-80DD-9369F62709C6/GUID-61471315-14E1-5A0F-A164-92CF928C3604">DoRegisterStaticResources()</xref>. </p> </section>

<section id="GUID-EBBEF707-27E5-4E10-ADCA-A02C119EB075"><title>Using

the Power Resource Manager</title> <p>Porting the PRM consists of

implementing the PSL layer for a given hardware platform and modifying

clients, such as device drivers, to use the PRM framework. </p> <p>The following tasks are covered in this tutorial: </p> <ul>

<li id="GUID-21093CEB-845E-528F-81DF-BD21084E3A27"><p> <xref href="GUID-B1CE51BC-B452-5FC9-9C00-35447AF40671.dita"> Implement the controllable

power resources</xref>, </p> </li>

<li id="GUID-93B8B5A9-D7EE-56A0-B96B-BA2FC8DE1CE7"><p> <xref href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita"> Implement the PSL

for the target</xref>, </p> </li>

<li id="GUID-417CE38C-66CC-5186-B833-B1A6E8CE21B8"><p> <xref href="GUID-E7F91A65-235D-589C-9A8C-0B207D19A24B.dita"> Port the client

drivers to use the PRM</xref> (to control the implemented resources), </p> </li>

<li id="GUID-1420B749-8618-5FF3-93E3-F1A5E4579061"><p> <xref href="GUID-C8DF0CB0-92F4-5F9E-A8F1-7DE50954C4F1.dita">Debugging the PRM</xref>, </p> </li>

<li id="GUID-4EEEC53B-C162-5E3F-B047-ABD4951F9C46"><p> <xref href="GUID-66E5F769-1156-54CA-94BC-8912159A1240.dita"> Testing the PRM

PSL</xref>. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita"><linktext>Power

Resource Manager (PRM)</linktext></link>

<link href="GUID-3773A78D-F491-52EB-AA1D-201636497F28.dita"><linktext>Power

Management Tutorials</linktext></link>