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-E7F91A65-235D-589C-9A8C-0B207D19A24B" xml:lang="en"><title>Port client drivers to use the PRM</title><shortdesc>This document describes how to port client drivers to use

    13 the PRM.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-B2FA7A9A-8BA2-4C9C-AFB0-8F2E73A5653B"><title>Purpose</title> <p>Device drivers must register as clients to access services of

    15 the PRM. </p> <p><b>Introduction</b> </p> <p>Kernel side components

    16 can access PRM services through exported kernel side APIs by including <filepath>resourceman.h</filepath> and linking against the static library provided

    17 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>

    18 <section id="GUID-E496B581-9C24-49BB-A7EA-7E1EE4AD7E39"><title>Porting

    19 client drivers </title> <p>Kernel side components register as clients

    20 with the PRM from their entry point during kernel boot and device

    21 drivers register as clients on channel opening. </p> <p>User side

    22 components can access PRM services through a user side proxy interface.

    23 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

    24 behaviour during resource state change and read operations (mainly

    25 on a long latency resource), clients should pre-allocate ‘client level’

    26 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

    27 of the PRM. </p> <p>Before de-registering as clients from PRM, device

    28 drivers must: </p> <ul>

    29 <li id="GUID-6469D50E-BA4B-5BD2-898D-701547B1119F"><p>Cancel any pending

    30 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

    31 before proceeding with deregistration as the asynchronous request

    32 has started processing and will run to completion, </p> </li>

    33 <li id="GUID-A9377536-9850-534D-BEFA-95493B74B938"><p>Cancel all resource

    34 state change notification requests issued by this client using <xref href="GUID-51CAD2A1-C978-3EBD-984F-4C5C59D68885.dita"><apiname>CancelNotification()</apiname></xref>, </p> </li>

    35 <li id="GUID-24C83DC4-C6F2-5AFA-916A-D405418CADDF"><p>Delete the asynchronous

    36 callback objects and notification objects created by this client to

    37 avoid memory leak. </p> </li>

    38 </ul> <p><b>Omissions </b> </p> <p>PRM APIs cannot be called from

    39 a Null thread, ISR or from DFC thread1. However it might be possible

    40 that ISR need to operate on a power resource, for example, a power

    41 supply may need to be turned on before a hardware register that an

    42 ISR is interested on can be read. In this case Base port developers

    43 need to access the power resource directly. In order for the PRM to

    44 provide a consistent view of power resources any resource manipulators

    45 in an ISR must leave them unchanged, so in the above example, the

    46 ISR must turn OFF the power supply after it read the registers. </p> </section>

    47 </conbody><related-links>

    48 <link href="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita"><linktext>Porting

    49 the Power Resource Manager</linktext></link>

    50 <link href="GUID-B1CE51BC-B452-5FC9-9C00-35447AF40671.dita"><linktext>Implement

    51 the controllable power resources</linktext></link>

    52 <link href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita"><linktext>Implement

    53 the PSL for the target</linktext></link>

    54 <link href="GUID-C8DF0CB0-92F4-5F9E-A8F1-7DE50954C4F1.dita"><linktext>Debugging

    55 the PRM</linktext></link>

    56 <link href="GUID-66E5F769-1156-54CA-94BC-8912159A1240.dita"><linktext>Testing

    57 the PRM PSL</linktext></link>

    58 </related-links></concept>