<?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 <xref href="GUID-9535CF67-7541-554E-BE5C-9FDDFDB58EA5.dita">targettype</xref> 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>