Mercurial Mercurial > oss > MCL > sftools > depl > docscontent / annotate
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Adaptation/GUID-E7F91A65-235D-589C-9A8C-0B207D19A24B.dita
author Graeme Price <GRAEME.PRICE@NOKIA.COM>
Fri, 15 Oct 2010 14:32:18 +0100
changeset 15 307f4279f433
permissions -rw-r--r--
Initial contribution of the Adaptation Documentation.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
15
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     1
 
<?xml version="1.0" encoding="utf-8"?>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     2
 
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     3
 
<!-- This component and the accompanying materials are made available under the terms of the License
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     4
 
"Eclipse Public License v1.0" which accompanies this distribution,
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     5
 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     6
 
<!-- Initial Contributors:
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     7
 
    Nokia Corporation - initial contribution.
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     8
 
Contributors:
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
     9
 
-->
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    10
 
<!DOCTYPE concept
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    11
 
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    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
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    13
 
the PRM.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    14
 
<section id="GUID-B2FA7A9A-8BA2-4C9C-AFB0-8F2E73A5653B"><title>Purpose</title> <p>Device drivers must register as clients to access services of
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    15
 
the PRM. </p> <p><b>Introduction</b> </p> <p>Kernel side components
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    16
 
can access PRM services through exported kernel side APIs by including <filepath>resourceman.h</filepath> and linking against the static library provided
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    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>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    18
 
<section id="GUID-E496B581-9C24-49BB-A7EA-7E1EE4AD7E39"><title>Porting
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    19
 
client drivers </title> <p>Kernel side components register as clients
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    20
 
with the PRM from their entry point during kernel boot and device
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    21
 
drivers register as clients on channel opening. </p> <p>User side
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    22
 
components can access PRM services through a user side proxy interface.
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    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
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    24
 
behaviour during resource state change and read operations (mainly
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    25
 
on a long latency resource), clients should pre-allocate ‘client level’
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    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
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    27
 
of the PRM. </p> <p>Before de-registering as clients from PRM, device
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    28
 
drivers must: </p> <ul>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    29
 
<li id="GUID-6469D50E-BA4B-5BD2-898D-701547B1119F"><p>Cancel any pending
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    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
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    31
 
before proceeding with deregistration as the asynchronous request
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    32
 
has started processing and will run to completion, </p> </li>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    33
 
<li id="GUID-A9377536-9850-534D-BEFA-95493B74B938"><p>Cancel all resource
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    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>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    35
 
<li id="GUID-24C83DC4-C6F2-5AFA-916A-D405418CADDF"><p>Delete the asynchronous
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    36
 
callback objects and notification objects created by this client to
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    37
 
avoid memory leak. </p> </li>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    38
 
</ul> <p><b>Omissions </b> </p> <p>PRM APIs cannot be called from
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    39
 
a Null thread, ISR or from DFC thread1. However it might be possible
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    40
 
that ISR need to operate on a power resource, for example, a power
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    41
 
supply may need to be turned on before a hardware register that an
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    42
 
ISR is interested on can be read. In this case Base port developers
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    43
 
need to access the power resource directly. In order for the PRM to
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    44
 
provide a consistent view of power resources any resource manipulators
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    45
 
in an ISR must leave them unchanged, so in the above example, the
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    46
 
ISR must turn OFF the power supply after it read the registers. </p> </section>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    47
 
</conbody><related-links>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    48
 
<link href="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita"><linktext>Porting
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    49
 
the Power Resource Manager</linktext></link>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    50
 
<link href="GUID-B1CE51BC-B452-5FC9-9C00-35447AF40671.dita"><linktext>Implement
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    51
 
the controllable power resources</linktext></link>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    52
 
<link href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita"><linktext>Implement
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    53
 
the PSL for the target</linktext></link>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    54
 
<link href="GUID-C8DF0CB0-92F4-5F9E-A8F1-7DE50954C4F1.dita"><linktext>Debugging
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    55
 
the PRM</linktext></link>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    56
 
<link href="GUID-66E5F769-1156-54CA-94BC-8912159A1240.dita"><linktext>Testing
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    57
 
the PRM PSL</linktext></link>
307f4279f433 Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff changeset 
    58
 
</related-links></concept>
MCL/sftools/depl/docscontent