<?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-6E1DE1E4-1B09-541C-8708-9126E69B42CE" xml:lang="en"><title>Power

Resource Manager (PRM)</title><shortdesc>Describes the Power Resource Manager.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<ul>

<li id="GUID-16097C0C-7354-5B9E-B405-1785F7511878"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-2F312E19-71BC-5396-996F-EA48EAEDF2F2">Introduction</xref>  </p> </li>

<li id="GUID-9780C08F-CBA2-5C72-B6D2-C751F3CF18C7"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-F830F456-A436-5025-821D-21855C7AE056">Concepts</xref>  </p> </li>

<li id="GUID-FBAB865C-C003-504A-A8DB-058C9BCA2D20"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-5C3F684C-D4F6-5343-AFFC-009B70210F9C">User-side</xref>  </p> </li>

<li id="GUID-6FE7DE11-1781-5F85-99B6-83B544148D3A"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-DE8EE84C-D46F-504A-8254-C212B7C5D5C1">Kernel-side</xref>  </p> </li>

</ul>

<section id="GUID-2F312E19-71BC-5396-996F-EA48EAEDF2F2"><title>Introduction</title> <p>The

Power Resource Manager (PRM) integrates the Symbian device driver with existing

power control and functions used for resource state changing and querying.

It defines an exported API that device drivers and other users of power resources

(represented by kernel-side components) can use to control the state of power

resources. The PRM assists the development of device drivers by removing the

need to understand the complexities of platform specific power resource management

by providing a simple to use generic framework. </p> <p>The PRM also allows

user-side clients to gain access to the services. Clients of the PRM can: </p> <ul>

<li id="GUID-1F23255C-A662-5755-A4C7-387A57FEB2C3"><p>request information

on the clients and resources registered with PRM </p> </li>

<li id="GUID-3E6406A9-757A-53EE-AE1C-839CA87C1120"><p>get the current state

of the resources </p> </li>

<li id="GUID-4FD981E6-EA1E-5E49-83D1-CC017BB753FE"><p>request changes to the

state of power resources </p> </li>

<li id="GUID-3ED36326-E905-53A1-907F-51DD6846B5BC"><p>request notification

of changes (i.e. power-down or change clock frequency) to the power resources

that they depend on. </p> </li>

</ul> <p>The following diagram shows the generic and customisable parts of

the framework: </p> <ul>

<li id="GUID-D4A341D5-84C4-543E-A392-426B6E9905FB"><p>exported kernel level

API (<xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita"><apiname>PowerResourceManager</apiname></xref>) </p> </li>

<li id="GUID-D0A636FF-9520-5CA1-82EF-E7B7AF645063"><p>base virtual class for

Power Resource Controller (<xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita"><apiname>DPowerResourceController</apiname></xref>) </p> </li>

<li id="GUID-C7C11053-E43B-5A1F-B5E7-6BBE36C02C1D"><p>PDD required for user-side

proxy client </p> </li>

<li id="GUID-404A1110-40E3-5E28-8C04-19232FB047B5"><p>platform specific implementation

of resource control at the level of register interface to hardware resource

controller (<codeph>DXXXPowerResourceController</codeph>) </p> </li>

</ul> <fig id="GUID-72B93745-2089-526F-8AF5-0E7522CADBEC">

<image href="GUID-99C4FCCC-9E8B-51CC-85F8-F03BE18DF19E_d0e82580_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-F830F456-A436-5025-821D-21855C7AE056"><title>Concepts</title> <ul>

<li id="GUID-3F2C2733-A287-5AB8-A695-4863EBA1FF52"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-4CC0C003-1952-5CAD-A7C5-163C5DDA52C8">Power resources</xref> </p> </li>

<li id="GUID-D4CDE568-00CA-50BD-A3CD-C12523B81180"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-8BBC100D-BB97-5675-AA2F-E730A0DF4B26">Clients</xref>  </p> </li>

</ul> <p id="GUID-4CC0C003-1952-5CAD-A7C5-163C5DDA52C8"><b>Power resources</b> </p> <p>A

power resource is anything that has an effect on power consumption. These

are typically platform specific and either physical or logical. Physical power

resources are provided by hardware: for example, clocks, outputs from voltage

regulators, switched power domains and performance levels. Logical power resources

do not directly map to hardware components, but their state has an effect

on overall power consumption. In this category we include, for example, shared

buses and devices that provide services to other components. </p> <p>Power

resources can be further categorised based on: </p> <ul>

<li id="GUID-CF16C658-A90F-5378-825B-CEC9C8D2DF1B"><p>Number of <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-8BBC100D-BB97-5675-AA2F-E730A0DF4B26">clients</xref>  </p> <p>A power resource can have a single user or it can

be shared. There is no limit to the number of clients sharing a resource.

If the resource is shared, then a request system is used. This comprises a

list of <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-F47D2098-16A7-5590-A68A-7AE4B2DAB462">client

level objects</xref>, one for each client requesting a level on the resource.

The resource level is determined by a set of rules which govern whether a

request is accepted or declined. </p> </li>

<li id="GUID-B5BBF273-19B4-5A3B-9B85-792837D70258"><p>States </p> <p>The <xref href="GUID-1D3E61BD-C09D-51FD-A10B-22392FDAEFEC.dita#GUID-1D3E61BD-C09D-51FD-A10B-22392FDAEFEC/GUID-1817A738-2351-526F-881D-7EB479E93C4C">resource

state</xref> may be binary, multi-level or multi-property. A binary state

is either On or Off and a multi-level state can change either discretely or

continuously between a minimum (which could be Off) and a maximum value (which

could be fully On). </p> <p>A multi-property resource has different properties

across different portions of the operating curve. For example, the level may

be controllable within the ‘operational’ part of that curve but have different

discrete fixed states for the ‘idle’ or ‘sleep’ modes of operation. </p> </li>

<li id="GUID-FC70680E-1595-54FC-A611-295688470176"><p>Execution time </p> <p>The

execution time of a resource can be either instantaneous or long latency.

An instantaneous resource can be operated almost immediately (no longer than

a few system clock cycles, comparable to a CPU instruction execution time).

Operations on long latency resources take a significant time to complete (a

non-negligible amount of CPU clock cycles). </p> <p>Power resources may be

long latency for state change operations and instantaneous for obtaining the

current state. This is typically the case of a PLL (Phase Locked Loop) device

(<xref href="http://en.wikipedia.org/wiki/Phase-locked_loop" scope="external">definition

from Wikipedia</xref>), which requires time to stabilise after a frequency

change is initiated but whose current output frequency can be read from a

register. <b>Note</b>: instantaneous operations may pre-empt operations on

long latency resources, and requests to get the state of a shared resource

may be issued while a state change is underway. If the read operation is instantaneous

and the change is long latency, care must be taken (at the PSL level) to not

return inconsistent values. </p> <p>Other power resources may be long latency

on both state change and state read operations. This is typically the case

for any resources accessed through an inter-IC bus (even if their operation

is instantaneous). </p> </li>

<li id="GUID-8ABE5ED4-C2CB-557E-BF53-9630567AE7DC"><p>Resource <i>sense</i>  </p> <p>Each

client sharing a resource may have a different requirement on its state. The

resource <i>sense</i> is used to determine whose requirement prevails. </p> <table id="GUID-BECBC606-95E8-5C6F-BC71-2DA2AA838C88">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p>Positive sense </p> </entry>

<entry><p>Can have their value increased without affecting their sharers. </p> <p>The

level is set to the highest level that is requested. The highest requirement

for binary resources is the On state. </p> </entry>

</row>

<row>

<entry><p>Negative sense </p> </entry>

<entry><p>Can have their value decreased without affecting their sharers. </p> <p>The

level is set to the lowest level that is requested. The lowest requirement

for binary resources is the Off state. </p> </entry>

</row>

<row>

<entry><p>Custom sense </p> </entry>

<entry><p>May be increased or decreased freely by some privileged sharers

but not by others, which are bound by the requirement of the privileged sharers. </p> <p>The

decision to change the prevailing level (or binary state) depends on the privileges

of the client and past usage of the resource. This decision is made by the

PSL <xref href="GUID-B1CE51BC-B452-5FC9-9C00-35447AF40671.dita#GUID-B1CE51BC-B452-5FC9-9C00-35447AF40671/GUID-9526B472-00ED-583A-8BFC-C02363D4DFA2">custom

function</xref> implementation. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </li>

<li id="GUID-CF996934-F142-5A79-BE7B-D91FE3109D95"><p>Static or Dynamic </p> <p>Most

power resources are known at device creation time, so their control should

be addressed by such components as the Variant or ASSP. These resources are

registered during the creation of the Resource Controller; these are static

resources. Resources controlled by device drivers (internal or external) are

only registered at driver-creation time using the registration and deregistration

API provided by the PRM; these are known as dynamic resources. </p> <p> <b>Note</b>:

Dynamic resources are only available when you use the extended library. 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</xref>. </p> </li>

</ul> <p>Physical resources may belong to one or more of these categories,

for example, a multilevel resource may be shared between different clients

and take a significant time to change state (long latency). </p> <p>External

devices may include and control their own power resources. In some cases,

an external device can function as a bus expander, allowing other devices

to be connected, and eventually share the power resources it controls. </p> <p id="GUID-121C14E3-D446-565E-AAAE-C43C131ACD3C"><b>Caching the prevailing level</b> </p> <p>The

PRM caches the prevailing level of each resource as well as the client that

requested it. The cached state is guaranteed to be the state that the resource

was in when the last request to change or read the state from its hardware

was issued. </p> <p>On resource state read operations, the PRM allows clients

to select the cached state instead of the current state of the hardware resource.

A cached state read is always an instantaneous operation executed in the context

of the calling client thread (even for long latency resources). </p> <p>However,

care must be taken as the cached state may not be the state the resource is

at that moment. For example, a resource can be non-sticky: when it is turned

on it stays on during an operation but then automatically switches itself

off. </p> <p>The consistency of the cached state relies on all resource state

operations being requested through the <xref href="GUID-4804B6E0-9199-5F3E-984A-4B00B3984E45.dita">Power

Resource Controller</xref>. </p> <p><b>Dynamic

resources</b> </p> <p>A generic layer provides basic functionality for static

resources an extended version of the PRM provides APIs for dynamic resources

and resource dependencies. These dynamic resource and resource dependent APIs

are only available through the extended library <filepath>resmanextended.lib</filepath>. </p> <p>A

dynamic resource is registered with the PRM using <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-1AB3CD4A-2BD3-366A-9359-791B3BBC9127"><apiname>PowerResourceManager::RegisterDynamicResource()</apiname></xref>.

This function is also used to register a dynamic resource that supports dependencies

between resources. </p> <codeblock id="GUID-0325A795-F99E-5098-947E-24A10C5D5416" xml:space="preserve">TInt RegisterDynamicResource(TUint aClientId, DDynamicPowerResource* aResource, TUint&amp; aResourceId)</codeblock> <p>Pass the ID of the client that requests the dynamic resource and the

dynamic resource (<xref href="GUID-CA01041D-8FD6-3B5B-BB5D-A5159DF7C9AB.dita"><apiname>DDynamicPowerResource</apiname></xref>) to register. The

PRM sets <codeph>aResourceId</codeph> to the resource ID of this resource.

Dynamic resources that support dependencies are derived from the class <xref href="GUID-6B224A9F-D2B9-3289-922D-766EF093FCD6.dita"><apiname>DDynamicPowerResourceD</apiname></xref>. </p> <p><b>Deregistering a dynamic resource</b> </p> <p>Use <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-8E388C73-F26D-30F7-9CA9-5ED0439E4C4D"><apiname>PowerResourceManager::DeRegisterDynamicResource()</apiname></xref> to

deregister a dynamic resource from the PRM. You can also use the function

to deregister a dynamic resource that supports a dependency. </p> <codeblock id="GUID-89FC49A8-FC66-5B8C-A82C-18987E2BA0E7" xml:space="preserve">TInt DeRegisterDynamicResource(TUint aClientId, TUint aResourceId, TInt* aState)</codeblock> <p> <codeph>aState</codeph> is a pointer to the final state that the resource is set

to before deregistration if this value is NULL the state of the resource is

changed to its default. </p> <p><b>Changing resource state on a dynamic resource </b> </p> <p>Because a dynamic

resource can deregister from the PRM it is necessary to indicate to clients

that this has happened. Any remaining notification requests are completed

with a -2 in the client field of the callback function. This indicates that

this notification is because the resource has been deregistered and not because

the notification conditions have been met. When a client recieves a notification

of this type the request notification should be cancelled using <xref href="GUID-51CAD2A1-C978-3EBD-984F-4C5C59D68885.dita"><apiname>CancelNotification()</apiname></xref>. </p> <p id="GUID-473BBE32-6831-52BE-8752-CB6DBBBABD2C"><b>Resource dependencies</b> </p> <p>A

resource may register a dependency on another resource. At least one of the

resources must be a dynamic resource. Request a dependency between resources

with <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-9C1BF3D5-6F5D-3BEF-9DF0-A5FED85CC718"><apiname>PowerResourceManager::RegisterResourceDependency()</apiname></xref>. </p> <codeblock id="GUID-EC9D5125-BC25-5196-88E7-3245B3B62AF4" xml:space="preserve">TInt RegisterResourceDependency(TUint aClientId, SResourceDependencyInfo* aResDependecyInfo1, SResourceDependencyInfo* aResDependencyInfo2)</codeblock> <p>This function is passed the ID of the client that sets the resource dependency

and the dependency information of the resource (<xref href="GUID-88FE83B0-35A1-3913-B38F-1FB925FFE96C.dita"><apiname>SResourceDependencyInfo</apiname></xref>). <codeph>SResourceDependencyInfo</codeph> contains

the resource ID and the priority of the dependency. </p> <p>The kernel will

panic if a closed loop dependency is found for the specified dependency or

if a resource with same dependency priority is already registered. </p> <p>Use <xref href="GUID-A3D65EA0-70B1-35E9-998D-EC4C1A294AB8.dita"><apiname>GetNumDependentsForResource()</apiname></xref> to

retrieve the number of resources that depend on the specified resource directly

and <xref href="GUID-9C582DAB-2C0B-331D-BA8D-CED067289055.dita"><apiname>GetDependentsIdForResource()</apiname></xref> to return the IDs of all

the dependent resources. </p> <p><b>Deregistering

resource dependencies</b> </p> <p>Use <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-127E979F-F540-36E2-A759-8ED408E89F38"><apiname>PowerResourceManager::DeRegisterResourceDependency()</apiname></xref> to

remove a dependency. This function takes the ID of the client that requests

the deregistration of the resource dependency and the IDs of the linked resources. </p> <codeblock id="GUID-561502A3-2603-5090-98F3-6BF714C8514B" xml:space="preserve">TInt DeRegisterResourceDependency(TUint aClientId, TUint aResourceId1, TUint aResourceId2)</codeblock> <p> <b>Note</b>: These functions are only available when you use the extended

library. </p> <p><b>Changing

resource state on a dependent resource</b> </p> <p>A resource state can change

when the state of any of its dependent resources changes. A state change causes

a notification if the requested conditions are met. The client ID in the callback

function is updated with the ID of the resource that triggered this resource

change (bit 16 of the ID is set for dependency resource; this is used to distinguish

between a resource ID and a client ID). </p> <p id="GUID-8BBC100D-BB97-5675-AA2F-E730A0DF4B26"><b>Clients</b> </p> <p>The

PRM has both user and kernel-side clients. Kernel-side clients are: </p> <ul>

<li id="GUID-7DDBF8D2-80AD-5248-9C8A-2F215E98513E"><p>device drivers </p> </li>

<li id="GUID-914A7E0F-9FE5-579A-AEB5-35163D89E450"><p>performance scaling

and/or performance monitoring and prediction components </p> </li>

</ul> <p>User-side clients are: </p> <ul>

<li id="GUID-E1A4D6C3-9EEC-54EB-BEF4-90C3DD65E4A3"><p>user-side system-wide

power management framework </p> </li>

<li id="GUID-08B28DD8-107E-5142-A887-F685A17915DC"><p>other power-aware servers

and power-aware applications </p> </li>

</ul> <p>Clients register with the PRM by name. Clients can request to allocate

and reserve client level objects and request message objects after registering

with PRM. </p> <p id="GUID-F47D2098-16A7-5590-A68A-7AE4B2DAB462"><b>Client level objects</b> </p> <p>Client

level objects represent a client requesting a level on a resource. They are

used by resources to set the current level of the resource and the current

owner of the resource level. </p> <p>Each resource has a doubly linked list

on which client level objects are held. When a client requests a level for

the first time, a new client level object is added to the list; however, if

the client already has an object on the list, this object is adjusted to reflect

the change in the required level. </p> <p>The following rules determine whether

the change is allowed on positive and negative sense resources: </p> <ul>

<li id="GUID-18D734C9-F01A-53D8-9B2B-9DED288F8968"><p>If the requested change

is in the direction permitted by the resource sense and would result in exceeding

the prevailing level, the change is allowed. </p> <p>The new prevailing level

is recorded, and the previous prevailing level and the requirements other

clients have on the resource remain on record. </p> </li>

<li id="GUID-9901C6DC-D91F-5CB4-BA68-10E941486BBF"><p>If the requested change

is not in the direction permitted by the resource sense, but the client requesting

the change is the owner of the prevailing level, the resource state changes

up to next highest for a positive sense resource, or lowest for a negative

sense resource. </p> <p>This value is now the prevailing level and the client

that requested it remains the owner of the prevailing level. </p> </li>

<li id="GUID-643C8DE3-322C-5C2A-840F-80F02DDFB60D"><p>If the requested change

is not in the direction permitted by the resource sense, and the client requesting

the change is not the owner of the prevailing level, the change is not allowed. </p> <p>Even

though the request was rejected, the client's existing requirement is adjusted

to reflect the request. </p> </li>

</ul> <p>Prevailing levels are recorded by either adjusting the previous requirement

for the client that requested it or, if it is the first time this client requests

a level, a new requirement is created. </p> <p id="GUID-8FE4BD6A-6A69-5233-88E2-32837A42A544"><b>Notifications</b> </p> <p>A

client may request a state change notification from a resource. Notifications

can be conditional or unconditional; conditional notifications specify a threshold

on the resources state, which when crossed in the direction specified, triggers

the notification. </p> <p>Notifications are always issued post resource change

and invoke callback functions executed in the context of the requesting client

thread. The process of notifying a client involves queuing a DFC in that clients'

thread. The notification object encapsulating the DFC must be created in kernel

heap and passed to the notification API by the client that requested the notification.

The client may share the same callback function between several notifications,

but a unique DFC must be created and queued per notification. </p> <p>Because

notifications result in DFCs being queued, it is not possible to guarantee

that all changes of resource state are notified. If the resource state changes

again before the first DFC runs, a separate notification cannot be generated.

It is also not possible to guarantee that by the time the notification callback

runs, the resource state is still the same as the state that caused the notification

to be issued: it is the responsibility of the driver to read the resource

state after receiving a notification. </p> </section>

<section id="GUID-5C3F684C-D4F6-5343-AFFC-009B70210F9C"> <title>User-side</title> <ul>

<li id="GUID-80696301-3BF7-5DBC-84DB-5961FB6D2F0E"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-B33A80C1-6079-556E-89D7-BC1F2304384D">Introduction</xref>  </p> </li>

<li id="GUID-E8D832DE-1879-5508-841D-90D87EE34E02"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-A5D4981F-4B16-5174-A41A-E9EEC70EA62C">Initialisation</xref>  </p> </li>

<li id="GUID-59F352F4-2602-59F5-BC3A-71544A092361"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-1DC958F3-7952-56C0-A8BC-F52B2A83BE3C">Getting power resource information</xref>  </p> </li>

<li id="GUID-8437EDA3-1E1E-588C-B25D-719EE6921350"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-8BDF9B79-BC05-593C-B39E-C6B8BD26AA2D">Requesting notifications</xref>  </p> </li>

<li id="GUID-465111CA-8F3B-52C9-85E9-F81CC0AB87FA"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-ACA22305-8990-54F5-8098-80716F4A5AAE">Changing the state of power resources</xref>  </p> </li>

</ul> <p id="GUID-B33A80C1-6079-556E-89D7-BC1F2304384D"><b>Introduction</b> </p> <p>The <xref href="GUID-FD3DEFC1-DA39-3A1A-8E00-A46B34B78899.dita"><apiname>RBusDevResManUs</apiname></xref> user-side

API makes relevant PRM functionality available to user-side applications that

have power-aware features. </p> <p> <codeph>RBusDevResManUs</codeph> is derived

from <xref href="GUID-6FBFA078-8253-3E24-B1F8-5F75E86C3066.dita"><apiname>RBusLogicalChannel</apiname></xref>, the user-side handle to a logical

channel base class, and presents the user-side interface to a kernel-side

LDD. The LDD is built as <filepath>resman.ldd</filepath>. </p> <p>The API

enables concurrent access by multiple clients, with one channel supported

for each. Sharing of channels between threads is not supported. </p> <p> <note> To

open a channel on the user-side API a client must exhibit the <xref href="GUID-4BFEDD79-9502-526A-BA7B-97550A6F0601.dita">PlatSec</xref> capability <codeph>PowerMgt</codeph>.</note></p><p> If a client wishes to access information

on kernel-side clients of the Resource Controller, it must also exhibit the <codeph>ReadDeviceData</codeph> capability. </p> <p id="GUID-A5D4981F-4B16-5174-A41A-E9EEC70EA62C"><b>Initialisation</b> </p> <p>Clients

do not need to explicitly load the kernel-side LDD, as this is a kernel extension

and so is loaded and initialised during kernel initialisation (attempts to

re-load it returns the error code <codeph>KErrAlreadyExists</codeph> but initialistation

otherwise appears successful). </p> <p>Clients open a channel on the LDD by

calling the <xref href="GUID-FD3DEFC1-DA39-3A1A-8E00-A46B34B78899.dita#GUID-FD3DEFC1-DA39-3A1A-8E00-A46B34B78899/GUID-505CFB46-E77B-38D2-AE50-B088D5D2B0F1"><apiname>RBusDevResManUs::Open()</apiname></xref> method. The client

passes a name to the method - ideally, this is the client’s component name.

It is the client’s responsibility to ensure the name is unique even if multiple

channels are opened. </p> <p>The client then needs to call the <xref href="GUID-E735AB4A-E9D5-33C7-ACEC-815013C0777A.dita"><apiname>Initialise()</apiname></xref> method

specifying the number of request objects required. The numbers passed to <codeph>Initialise()</codeph> determine

the extent of memory allocation required (in part by the LDD and in addition

by request to the Resource Controller) and also the maximum number of concurrent

client requests supported. </p> <p>The number of request objects created at

initialisation should be the maximum number of concurrent (asynchronous) requests

that the client expects to have outstanding at any time. </p> <p id="GUID-1DC958F3-7952-56C0-A8BC-F52B2A83BE3C"><b>Getting power resource information</b> </p> <p> <xref href="GUID-FD3DEFC1-DA39-3A1A-8E00-A46B34B78899.dita#GUID-FD3DEFC1-DA39-3A1A-8E00-A46B34B78899/GUID-778D2DB8-A3B4-3F70-BFF0-3EB7B4D68866"><apiname>RBusDevResManUs::GetResourceInfo()</apiname></xref> is a method to retrieve the information for a specified resource, which

it returns in a <xref href="GUID-A1DDD3E3-C009-3C02-895B-0B2D0EE67A9D.dita"><apiname>TResourceInfo</apiname></xref> object. There is also a method

to get all the information for all the resources (<xref href="GUID-CF17E4E8-CFBC-31C2-B1CC-84D78006D046.dita"><apiname>GetAllResourcesInfo()</apiname></xref>).

This function requires the allocation of buffer memory in which the information

for all the resources is returned. <xref href="GUID-D3AB721D-35AB-36F9-B08D-10E44B6B8129.dita"><apiname>GetNoOfResources()</apiname></xref> returns

the total number of resources available for access. </p> <p>The example below

shows these functions in use. The amount of resources available are returned

by <codeph>GetNoOfResources</codeph>. This figure is used to calculate the

size of the buffer that is populated with the resource information by the <codeph>GetAllResourcesInfo</codeph> method. </p> <codeblock id="GUID-BB6AC0F1-DC41-51EE-ADA3-1402B3C3E90E" xml:space="preserve"> TInt r = KErrNone;

 TUint numResources=0;

    if((r=gChannel.GetNoOfResources(numResources))!=KErrNone)

        {

        // Failed

        return r;

        }

    RBuf buffer;

    if((buffer.Create(numResources*sizeof(TResourceInfo)))!=KErrNone)

        {

        // Failed

        return KErrGeneral;

        }

    buffer.SetLength(numResources*sizeof(TResourceInfo));

    if((r=gChannel.GetAllResourcesInfo(buffer,numResources))!=KErrNone)

        {

        // Failed

        return r;

        }</codeblock> <p>Get the current resource state with <xref href="GUID-79CC3D60-3B7B-3FC2-8067-205165281E28.dita"><apiname>GetResourceState()</apiname></xref>.

Passing <codeph>ETrue</codeph> results in the cached state being read rather

than the current hardware state. The cached state is guaranteed to be the

state that the resource was in when it was last changed or read from hardware.

This is why it is important that all change requests are carried out through

the Resource Controller. <codeph>readValue</codeph> returns the current prevailing

level and <codeph>levelOwnerId</codeph> the ID of the client that owns the

prevailing level. <codeph>GetResourceState()</codeph> can be cancelled using <xref href="GUID-BD242DA6-1D09-3770-94BF-CCCB396AEBE4.dita"><apiname>CancelGetResourceState()</apiname></xref> passing

the resource ID of the resource that the original request was on. Use the

method <xref href="GUID-2306456B-6502-3E49-B707-885D994E01C5.dita"><apiname>GetResourceIdByName()</apiname></xref> to get the ID of a resource

from the resource's name. </p> <codeblock id="GUID-FA4561F7-9223-542E-9B3C-2E03AB06FE28" xml:space="preserve">// Get initial state

TRequestStatus status;

TBool cached = EFalse;

TInt readValue;

TInt levelOwnerId = 0;

gChannel.GetResourceState(status, gSharedResource, cached, &readValue, &levelOwnerId);

User::WaitForRequest(status);</codeblock> <p> <xref href="GUID-EABEB759-9BF4-3278-B14C-8B887007C1D3.dita"><apiname>GetNumClientsUsingResource()</apiname></xref> and <xref href="GUID-000DC2CE-9C7B-3C0C-AABF-2D5B2C2EFA1D.dita"><apiname>GetNumResourcesInUseByClient()</apiname></xref> are used to retrieve the numbers of clients using a resource and the number

of resources in use by a client, respectively. <xref href="GUID-EADA4695-1058-34B6-963C-42BFC794C296.dita"><apiname>GetInfoOnClientsUsingResource()</apiname></xref> and <xref href="GUID-8C32B87E-0EBB-34EF-8C6B-6AB159B4CB09.dita"><apiname>GetInfoOnResourcesInUseByClient()</apiname></xref> complement the last two methods by retrieving the resource information for

each resource that is in use by a specified client or retrieving the client

information for each client using the specified resource. </p> <p>The API

supports receiving a number of concurrent (asynchronous) requests from a client;

the maximum number is determined by the number of resources that were specified

at initialisation. If a client issues a request that exceeds its allocation,

the error code <codeph>KErrUnderflow</codeph> is returned. </p> <p>Some synchronous

methods take a binary value, <codeph>aIncludeKern</codeph>, which defaults

to <codeph>EFalse</codeph>. If this parameter is set to <codeph>ETrue</codeph>,

the API attempts to return information that includes kernel-side clients. </p> <p id="GUID-8BDF9B79-BC05-593C-B39E-C6B8BD26AA2D"><b>Requesting notifications</b> </p> <p>Clients

can request to be notified when a resource changes its state using the <xref href="GUID-FD3DEFC1-DA39-3A1A-8E00-A46B34B78899.dita#GUID-FD3DEFC1-DA39-3A1A-8E00-A46B34B78899/GUID-E1EE8324-E39F-3094-9BF1-932706B35DC1"><apiname>RBusDevResManUs::RequestNotification()</apiname></xref> method.

Clients can also request to be notified when a resource reaches a specified

threshold in a specified direction (positive or negative <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-4CC0C003-1952-5CAD-A7C5-163C5DDA52C8">resource sense</xref>) using the same method but also passing it threshold

and direction values. </p> <p>To cancel a notification, use <xref href="GUID-51CAD2A1-C978-3EBD-984F-4C5C59D68885.dita"><apiname>CancelNotification()</apiname></xref> passing

the resource ID from which the notification was requested. <b>Note</b>: Any

notifications issued by a client must be cancelled before the client deregisters. </p> <p>It

is not guaranteed that all changes of resource state result in a notification

– a resource may change state more than once before a notification request

is completed. In addition, it is not guaranteed that a resource is in the

same state as it was when the notification was generated. For these reasons,

it is the responsibility of the user-side client to read the state of a resource

after receiving a notification. </p> <p id="GUID-ACA22305-8990-54F5-8098-80716F4A5AAE"><b>Changing the state of power

resources</b> </p> <p>To change a resource state call the asynchronous <xref href="GUID-9E260255-90BB-3D17-9A23-F02C8FCD3D72.dita"><apiname>ChangeResourceState()</apiname></xref> method

passing the ID of the resource on which the change is being requested and

the requested state. </p> <p> <xref href="GUID-181BB8BF-EA17-3A5E-8B70-94265CBD15E1.dita"><apiname>CancelChangeResourceState()</apiname></xref> cancels

all the <codeph>ChangeResourceState()</codeph> outstanding requests from the

client on the specified power resource. For each outstanding request, the

request object is removed from the doubly linked list within the Resource

Controller and returned to the request object pool. </p> </section>

<section id="GUID-DE8EE84C-D46F-504A-8254-C212B7C5D5C1"> <title>Kernel-side</title> <p>The Power Resource Manager component is implemented

as a kernel extension. It has an exported public interface accessible to kernel-side

components. Kernel components link to the resource manager kernel extension

DLL (<filepath>resman.lib</filepath>). Extended features are compiled and

exported in an additional library (<filepath>resmanextended.lib</filepath>).

The export library is built from the generic layer. </p> <p>To ease the development

of the PRM including the functionality provided by the generic layer and the

mandatory PSL implementation, the generic layer is compiled into a kernel

library (klib) (<filepath>resmanpsl.lib</filepath> for the basic version and <filepath>resmanextendedpsl.lib</filepath> for

the extended version) which is included by the PSL to produce the kernel extension. </p> <ul>

<li id="GUID-5D5302A9-1C1B-5B75-A203-64526CDDEB3E"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-F5E775AB-F428-5800-8844-20A1BA41380D">Concepts</xref>  </p> </li>

<li id="GUID-2A6C1709-1DE5-5A2F-B925-E81763B85EB0"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-7745C72D-DBFA-5E96-B0EB-497329A5A77D">Registration and initialisation</xref>  </p> </li>

<li id="GUID-8B1D1CF6-06D0-5C95-8C86-747EAE9C80E8"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-A20D5070-99F1-5B1E-9D3E-D8769030BDEE">Deregistration</xref>  </p> </li>

<li id="GUID-4D39457D-6193-5C0A-9858-B8BAF957D0CA"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-7F518094-4B91-5EA7-AAFA-8ABC8D7F77CE">Requesting power resource information</xref>  </p> </li>

<li id="GUID-4B572D4B-EEA9-53A5-A260-01DE4853B5CE"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-AA2EABEC-477F-54BD-AD1A-F2EF7B6BA5B7">Changing the state of power resources</xref>  </p> </li>

<li id="GUID-6768FCC6-3FC2-532E-9BB9-16BE4C4EE44C"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-198CE312-343E-535D-8EE5-D615A7AC9265">Requesting notifications</xref>  </p> </li>

</ul> <p id="GUID-F5E775AB-F428-5800-8844-20A1BA41380D"><b>Concepts</b> </p> <ul>

<li id="GUID-646E0C0A-6E4D-5FA0-83CD-6BE04B08E4BC"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-E8F3AF8E-387C-5285-A2B2-0B067F01BC3A">Requests</xref>  </p> </li>

<li id="GUID-9D5A30A8-7214-5D82-A819-B5594339A71C"><p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-0A8C9B3F-C96B-589C-819C-07D4C167BFCD">Callbacks</xref>  </p> </li>

</ul> <p id="GUID-E8F3AF8E-387C-5285-A2B2-0B067F01BC3A"><b>Request messages</b> </p> <p>Request

message objects represent a request for an operation on a resource by a client.

For example a request to change a resource's level or notification if a resource's

level changes. </p> <p>The client may attempt to increase its quota by requesting

the allocation of request messages, but this may fail with <xref href="GUID-64F6761A-4716-37C3-8984-FF18FC8B7B7D.dita"><apiname>KErrNoMemory</apiname></xref>.

A long latency resource request on may fail with <xref href="GUID-3673F75F-655F-3561-BD56-F7E1C6980810.dita"><apiname>KErrUnderflow</apiname></xref> if

the number of request messages pre-allocated by the client has been exceeded

and no more messages are left in the free pool to satisfy the request. </p> <p>The

pre-allocation and reservation of <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-F47D2098-16A7-5590-A68A-7AE4B2DAB462">client

levels</xref> and request messages is synchronously serviced in the context

of the calling client, although this may result in memory allocation that

is not time bound. </p> <p>See <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-2DE84E1F-C466-5631-A007-EEF046905388">Pre-allocating

client level and request message objects</xref> for implementation guidelines. </p> <p id="GUID-0A8C9B3F-C96B-589C-819C-07D4C167BFCD"><b>Callbacks</b> </p> <p>A

callback object is a customised DFC that is used to signal the completion

of notifications and the PRM's asynchronous APIs. Use the class <xref href="GUID-9B43C51D-56F7-35E0-BDD5-5D2F27924383.dita"><apiname>TPowerResourceCb</apiname></xref> to

create a resource callback object that encapsulates callback functions. </p> <p>The

resource callback object is initialised with a callback function <xref href="GUID-F42CE2D1-6859-352A-89A7-01DFBB1FE249.dita"><apiname>TPowerResourceCbFn</apiname></xref>,

a pointer to data passed to the callback function, the priority of the DFC

within the queue (0 to 7, where 7 is highest) and optionally, a pointer to

the DFC queue that this DFC should use. </p> <codeblock id="GUID-11947A50-7639-550D-BFB0-3B6320088065" xml:space="preserve">inline TPowerResourceCb(TPowerResourceCbFn aFn, TAny* aPtr, TInt aPriority)</codeblock> <p>This one specifies the DFC queue: </p> <codeblock id="GUID-21FE792B-24A2-502C-AA9E-EE8092573DA7" xml:space="preserve">inline TPowerResourceCb(TPowerResourceCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority)</codeblock> <p>The user specified callback function is invoked with five arguments: </p> <ul>

<li id="GUID-0912EE6D-A1DC-528D-8AEE-423D703C12CA"><p>the ID of the client

is: </p> <ul>

<li id="GUID-27C7A49B-BFCB-5D96-A129-7AE19A1CB430"><p>the client that issued

an asynchronous operation - if the callback function is called as a result

of an asynchronous resource state read operation </p> </li>

<li id="GUID-F4181885-29F6-53DB-8555-EB735EF83F81"><p>the client that is currently

holding the resource - if the callback function is called as a result of an

asynchronous resource state change operation or resource state change notification. </p> </li>

<li id="GUID-E8720BBB-BF9A-53FB-A123-AACA62A4F435"><p> <b>Note</b>: </p> <ul>

<li id="GUID-87393CD1-684C-503C-9A2A-982961FC8169"><p>If -1 is passed as the

client ID this specifies that no client is currently holding the resource. </p> </li>

<li id="GUID-A3AB501B-004A-538E-B811-6733C76D213C"><p>In the extended version

of PRM (see Dynamic and Dependant resources) if -2 is passed as the client

ID in the callback function it signifies that the dynamic resource is deregistering.

With dependency resources, the ID of the dependent resource is passed as the

client ID if the state of the resource (specified in <codeph>aResourceId</codeph>)

changes as a result of the dependant resources stage changing (whose ID is

specified in <codeph>aClientId</codeph>). </p> </li>

</ul> </li>

</ul> <ul>

<li id="GUID-A38B31E5-DB85-561A-A256-CF6FF025D9B0"><p>issued an asynchronous

API (state read or change) which leads to the callback function being called </p> </li>

<li id="GUID-F58DA60D-CA0E-5F82-9655-F1FF4D53D8B5"><p>requested the resource

state change that leads to queuing a notification, which then leads to the

callback function being called. </p> </li>

</ul> </li>

<li id="GUID-7ABBA59B-71A0-55CC-9722-5A569F95A881"><p>the resource ID - a

client may have multiple notifications pending on different resources and

a single callback function. The resource ID can be used to specify which resource

change is being notified </p> </li>

<li id="GUID-D18973A1-1E60-5335-BF98-1CCEB229730E"><p>the level of the resource

when either: </p> <ul>

<li id="GUID-9AC96325-FA2E-552F-A306-B0CCDA95B5BD"><p>the callback is called

as a result of a notification of state change </p> </li>

<li id="GUID-3886E475-28C5-5410-8801-0F4E9B273F13"><p>when the callback is

called as a result of a non-blocking form of <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-318F8627-AB72-3AA9-93A8-F8131117FF90"><apiname>PowerResourceManager::GetResourceState()</apiname></xref>. </p> </li>

<li id="GUID-5C65D90E-A9C8-5439-A8FE-B077AC00F4AF"><p>the requested level

for the resource when the callback is called as a result of a non-blocking

form of <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-9E89A793-A838-3E48-AC24-17367E36EC05"><apiname>PowerResourceManager::ChangeResourceState()</apiname></xref>  </p> </li>

</ul> </li>

<li id="GUID-56181048-98E7-57BB-81D9-D863663F44C2"><p>the ID of the resource

level owner </p> </li>

<li id="GUID-5924CF16-4493-5845-ADB0-615968D9D8C7"><p>the error code returned

when the callback is called as a result of an asynchronous request to change

the state of the resource. This is not relevant when the callback is called

as a result of a notification of state change </p> </li>

<li id="GUID-8BAD3C01-7AA1-5C42-A52F-05C1BF5957D0"><p>a user defined argument

that is passed to the constructor. </p> </li>

</ul> <p>Cancel an asynchronous request, or its callback, by calling <xref href="GUID-98C67010-FAD0-3D09-BFBF-EE240ADB95E7.dita"><apiname>CancelAsyncRequestCallback()</apiname></xref>. </p> <p id="GUID-7745C72D-DBFA-5E96-B0EB-497329A5A77D"><b> Registration and initialisation</b> </p> <p>Clients

need to register with the PRM using <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-4F932142-C551-3DBB-8DC8-F697B92E8168"><apiname>PowerResourceManager::RegisterClient()</apiname></xref> before

they can request operations on resources. </p> <p>Registration happens at

different times for different clients: </p> <ul>

<li id="GUID-491C4B9C-86BC-5AC2-870A-0FA46FDE3CA9"><p>kernel extensions register

from their entry point during kernel boot </p> </li>

<li id="GUID-8A6D66CC-DD34-5CC2-9AD3-BEEC7B540BA8"><p>device drivers for internal

or external devices register on opening a channel. </p> </li>

</ul> <p>When a client registers with the PRM, a client link object is removed

from the free pool, populated with the relevant information, and a pointer

to it is added to a container of clients within the PRM. If no free link exists

within the pool, a number of client links are created in kernel heap. As a

result, client registration may fail in out of memory situations. Client links

are never destroyed after the client deregisters, but are released back into

the free pool. </p> <p>Clients are registered by name; the PRM does not check

that a name is unique unless the <codeph>DEBUG_VERSION</codeph> macro is enabled.

The component registering the client should check that the name is unique.

The ID returned is a handle to the client link object that represents the

client in the PRM. </p> <p>On registration, a client also specifies the type

of ownership (<xref href="GUID-19F111C8-00AC-3A2E-85A6-755DC322C870.dita"><apiname>TOwnerType</apiname></xref>) that applies. This is either: </p> <ul>

<li id="GUID-E7A9ADE9-8590-5CB0-ADE9-8354BADCE77D"><p> <codeph>EOwnerThread</codeph> -

the client ID is only used by the thread that registered the client to call

the PRM APIs </p> </li>

<li id="GUID-9EED259E-E339-59E0-BE96-8A33EA01AE98"><p> <codeph>EOwnerProcess</codeph> -

the client ID is used by all threads in the process to call the PRM APIs. </p> </li>

</ul> <p>The default is <codeph>EOwnerProcess</codeph>. </p> <p id="GUID-2DE84E1F-C466-5631-A007-EEF046905388"><b>Pre-allocating client level

and request message objects </b> </p> <p>The controller has an initial pool

of free client levels and request messages whose size can be configured at

build time by the PSL. After registering with the PRM, a client can request

the pre-allocation of a number of client levels and request messages to guarantee

deterministic behaviour (to avoid out of memory failure) of the resource state

change operation using <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-F787A2A2-8860-3145-97FB-46D6B8D6E5AC"><apiname>PowerResourceManager::AllocReserve()</apiname></xref>.

This allocation remains reserved to the specified client until the client

is deregistered from the PRM. The number of client level objects reserved

by a client depends on the number of resources on which a resource state change

will be requested. </p> <p>A client may issue more than one request, possibly

to the same resource, before the previous one completes, it is therefore more

difficult to determine how many objects to pre-allocate. </p> <p>It is recommended

that as many request messages as asynchronous long latency resources the client

expects to use are pre-allocated. The free pool should be relied on for the

situations when a resource is requested more than once before the first request

completes. </p> <p id="GUID-A20D5070-99F1-5B1E-9D3E-D8769030BDEE"><b>Deregistration</b> </p> <p>All

notifications and asynchronous requests must be cancelled before the client

is deregistered, otherwise the kernel will panic. Use the <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-C076174C-D16A-3A8B-825C-F7BE2424EA3D"><apiname>PowerResourceManager::CancelNotification()</apiname></xref> and <xref href="GUID-98C67010-FAD0-3D09-BFBF-EE240ADB95E7.dita"><apiname>CancelAsyncRequestCallback()</apiname></xref> methods to cancel all pending notifications and asynchronous requests. Notifications

that have been registered with the Controller should be deregistered before

they are deleted as the Controller may attempt to issue them. Deleting a notification

that is still registered with the Controller results in the kernel panicking. </p> <p> <xref href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita#GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE/GUID-F47D2098-16A7-5590-A68A-7AE4B2DAB462">Client

level objects</xref> and request objects reserved by the client remain reserved

for that client until it deregisters. When the client is deregistering these

objects are moved to free pool by the PRM. </p> <p>Client deregistration can

result in a resource state change: </p> <ul>

<li id="GUID-8C4B2F9D-7B4D-5BC4-8B8C-02D1AEFDF1C5"><p>If the resource is shared

and the deregistering client owned the prevailing level, the resource state

is moved to the next level according to its sense. If it is a custom sense

resource, the resource state is changed as a result of calling a custom function. </p> </li>

<li id="GUID-DE1341E0-C392-5982-8A0D-3CCE9A8DC950"><p>If the resource is not

shared or if it is shared but the client is the only one using it at the time

of deregistration, the resource is moved to the <i>default</i> state. The

default state is only known by the PSL. </p> </li>

</ul> <p>A deregistering client can have a number of active requirements on

a number of resources and more than one of these resources may need to change

state as a result of the client deregistering. The combined operation of deregistering

the client and adjusting the state of all resources it shares executes synchronously.

That is, the client thread is blocked throughout whether the resources whose

state needs to change is instantaneous or long latency. </p>  <p id="GUID-7F518094-4B91-5EA7-AAFA-8ABC8D7F77CE"><b>Getting power resource information</b> </p> <p>The

resource information can be retrieved using the method <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-AFD3385B-362B-3F8B-B7EF-262CB21C0EE2"><apiname>PowerResourceManager::GetResourceInfo()</apiname></xref>,

information can also be retrieved for all of the resources used by the specified

client using <xref href="GUID-8C32B87E-0EBB-34EF-8C6B-6AB159B4CB09.dita"><apiname>GetInfoOnResourcesInUseByClient()</apiname></xref>. This function

takes a buffer that must be the size of the information structure multipled

by the number of resources in use by the client, this figure can be retrieved

using the method <xref href="GUID-000DC2CE-9C7B-3C0C-AABF-2D5B2C2EFA1D.dita"><apiname>GetNumResourcesInUseByClient()</apiname></xref>. Specify

the resource ID as zero to retrieve all information from all the clients registered

with PRM. </p> <p>To get information about clients using a resource, use the

method <xref href="GUID-EADA4695-1058-34B6-963C-42BFC794C296.dita"><apiname>GetInfoOnClientsUsingResource()</apiname></xref>. Use the number

of clients using a resource using <xref href="GUID-EABEB759-9BF4-3278-B14C-8B887007C1D3.dita"><apiname>GetNumClientsUsingResource()</apiname></xref>.

Specify the client ID as zero to retrieve all information from all the resources

registered with PRM. </p> <p>Use <xref href="GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00.dita#GUID-40AB9EDA-16CB-371E-8759-1D7C99FF9C00/GUID-318F8627-AB72-3AA9-93A8-F8131117FF90"><apiname>PowerResourceManager::GetResourceState()</apiname></xref> to

retrieve resource state information. This function can be called synchronously

or asynchronously. Asynchronous calls require the client to create a callback

object in the kernel heap or data section. The synchronous <codeph>GetResourceState()</codeph> call. </p> <codeblock id="GUID-00E075BB-E38B-5B15-A7DA-56C032A678C2" xml:space="preserve">TInt GetResourceState(TUint aClientId, TUint aResourceId, TBool aCached, TInt&amp; aState, TInt&amp; aLevelOwnerId);</codeblock> <p>The asynchronous <codeph>GetResourceState()</codeph> call. </p> <codeblock id="GUID-20C6EB70-1CF2-5FDD-85F8-577361E6CA86" xml:space="preserve">TInt GetResourceState(TUint aClientId, TUint aResourceId, TBool aCached, TPowerResourceCb&amp; aCb);</codeblock> <p>If executing asynchronously, the callback function encapsulated in the

callback object (called in the client’s context) is invoked when the state

of the resource is available. The third argument of the callback function

carries the resource state. If this function is called with <codeph>aCached</codeph> set

as <codeph>ETrue</codeph>, then the callback function is called in the context

of the calling thread both for instantaneous and long latency resources, thus

blocking the calling thread throughout. </p> <p>For instantaneous resources, <xref href="GUID-79CC3D60-3B7B-3FC2-8067-205165281E28.dita"><apiname>GetResourceState()</apiname></xref> executes

in the context of the calling thread and, if specified, the callback function