<?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-E7F91A65-235D-589C-9A8C-0B207D19A24B" xml:lang="en"><title>Port
client drivers to use the PRM</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This document describes how to port client drivers to use the PRM. </p>
<section id="GUID-B2FA7A9A-8BA2-4C9C-AFB0-8F2E73A5653B"><title>Purpose</title> <p>Device drivers must register as clients
to access services of the PRM. </p> <p><b>Introduction</b> </p> <p>Kernel
side components can access PRM services through exported kernel side APIs
by including <filepath>resourceman.h</filepath> and linking against the static
library provided by the PRM. See <xref href="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita#GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9/GUID-0F328055-DBCE-5B2B-A1EB-77F73BA1FC82">setup
and configuration requirements</xref>. </p> </section>
<section id="GUID-E496B581-9C24-49BB-A7EA-7E1EE4AD7E39"><title>Porting client drivers </title> <p>Kernel side components
register as clients with the PRM from their entry point during kernel boot
and device drivers register as clients on channel opening. </p> <p>User side
components can access PRM services through a user side proxy interface. See <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-5C3F684C-D4F6-5343-AFFC-009B70210F9C">user-side</xref> for
more information. </p> <p>To guarantee deterministic behaviour during resource
state change and read operations (mainly on a long latency resource), clients
should pre-allocate ‘client level’ objects and request objects using <xref href="GUID-975D07BD-21A8-3797-916A-AD5D63ADE33B.dita"><apiname>AllocReserve()</apiname></xref>.
This needs to be done immediately after registering as clients of the PRM. </p> <p>Before
de-registering as clients from PRM, device drivers must: </p> <ul>
<li id="GUID-6469D50E-BA4B-5BD2-898D-701547B1119F"><p>Cancel any pending asynchronous
request with <xref href="GUID-98C67010-FAD0-3D09-BFBF-EE240ADB95E7.dita"><apiname>CancelAsyncRequestCallback()</apiname></xref>. If <codeph>CancelAsyncRequestCallback</codeph> returns <codeph>KErrInUse</codeph> the
client must wait for the request to complete before proceeding with deregistration
as the asynchronous request has started processing and will run to completion, </p> </li>
<li id="GUID-A9377536-9850-534D-BEFA-95493B74B938"><p>Cancel all resource
state change notification requests issued by this client using <xref href="GUID-51CAD2A1-C978-3EBD-984F-4C5C59D68885.dita"><apiname>CancelNotification()</apiname></xref>, </p> </li>
<li id="GUID-24C83DC4-C6F2-5AFA-916A-D405418CADDF"><p>Delete the asynchronous
callback objects and notification objects created by this client to avoid
memory leak. </p> </li>
</ul> <p><b>Omissions </b> </p> <p>PRM APIs cannot be called from a Null thread,
ISR or from DFC thread1. However it might be possible that ISR need to operate
on a power resource, for example, a power supply may need to be turned on
before a hardware register that an ISR is interested on can be read. In this
case Base port developers need to access the power resource directly. In order
for the PRM to provide a consistent view of power resources any resource manipulators
in an ISR must leave them unchanged, so in the above example, the ISR must
turn OFF the power supply after it read the registers. </p> </section>
</conbody><related-links>
<link href="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita"><linktext>Porting the
Power Resource Manager</linktext></link>
<link href="GUID-B1CE51BC-B452-5FC9-9C00-35447AF40671.dita"><linktext>Implement
the controllable power resources</linktext></link>
<link href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita"><linktext>Implement
the PSL for the target</linktext></link>
<link href="GUID-C8DF0CB0-92F4-5F9E-A8F1-7DE50954C4F1.dita"><linktext>Debugging
the PRM</linktext></link>
<link href="GUID-66E5F769-1156-54CA-94BC-8912159A1240.dita"><linktext>Testing the
PRM PSL</linktext></link>
</related-links></concept>