<?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>
</related-links></concept>