<?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-3B6544CD-FA6E-5AB2-AA63-61186F52167D" xml:lang="en"><title>Controllable
Power Resources</title><shortdesc>This topic explains how power resources were controlled in older
releases of Symbian platform. For later releases see the Power Resource Manager
documentation.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>This documentation is retained for reference for those working with hardware
or software that is based on older versions of Symbian platform version (in
particular old release 9.5). For later releases see the <xref href="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9.dita">Porting
the Power Resource Manager</xref> documentation.</p>
<p>Controllable power resources are defined as being any device resource,
such as voltages on power-lines or clocks, which can be independently enabled,
disabled or modified under software control. </p>
<p>The following hardware block diagram is an example of the way power resources
might be arranged: </p>
<fig id="GUID-41113C18-2C87-5DEA-9D05-31083F51269A">
<title>Example power resource arrangement</title>
<image href="GUID-622D6337-E60A-5252-8B2B-BA8232927453_d0e29152_href.png" placement="inline"/>
</fig>
<p>There is no default support or default implementation for controllable
power resources in the generic layers of Symbian platform. They must be managed
by the base port. </p>
<p>We suggest that the management of controllable power resources (the resource
manager) be implemented in the Variant DLL or the ASSP DLL. This allows the
resource manager to be up and running by the time peripheral drivers, which
might also be kernel extensions, are loaded. See the <xref href="GUID-984C2A0D-36BE-5A99-9D65-3F8791C669FF.dita#GUID-984C2A0D-36BE-5A99-9D65-3F8791C669FF/GUID-95C34114-F986-5428-9D40-5CF64429CDBD">ASSP/Variant Architecture</xref> and the <xref href="GUID-ECAC3FF3-CDB2-5153-AD76-90732BA83726.dita#GUID-ECAC3FF3-CDB2-5153-AD76-90732BA83726/GUID-F55D88DB-7DE1-5069-BAE7-A7FE3750D065">ASSP/Variant
Tutorials</xref>. </p>
<p>A suggested implementation has the instance of the <xref href="GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D.dita"><apiname>Asic</apiname></xref> derived
class owning a pointer to the resource manager object. The interface class
for the ASSP or Variant could then have an exported or an inline member function
to return a pointer to this resource manager object. Peripheral drivers are
expected to link against either the ASSP DLL, or the Variant DLL, or both. </p>
<p>For example, for a device that has a Variant and an ASSP: </p>
<codeblock id="GUID-049CEE21-944A-589A-9F1B-8F031D681198" xml:space="preserve">class MyVariant : public MyASSP
    {
public:
    Init1();
    Init3();
    // Other mandatory Asic-derived member functions
    ...
public:
    ResourceManager* myResMgrPtr;
    ...
    };
      </codeblock>
<p>where class <codeph>MyASSP</codeph> is derived from class <xref href="GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D.dita"><apiname>Asic</apiname></xref>. </p>
<codeblock id="GUID-E8346FFB-1B0F-5482-9DF7-207B1B1948F8" xml:space="preserve">GLREF_D MyVariant TheVariant;</codeblock>
<codeblock id="GUID-CEF1F0C7-62E4-52B1-9830-DBD32B2BE8CE" xml:space="preserve">class TMyVariant
    {
public:
    inline static ResourceManager* ResourceManager()
        {return(TheVariant.myResMgrPtr);}
    // other exported methods
    ...
    };
      </codeblock>
<p>where <codeph>TMyvariant</codeph> is the Variant interface class, and <codeph>ResourceManager</codeph> is
the resource manager class. </p>
<p>The resource manager can be declared as a global object at the Variant
(or ASSP) scope and can therefore be created when this component is first
loaded. In this case, the <xref href="GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D.dita#GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D/GUID-FE55E398-7F08-384F-9E74-2CC2E45002B6"><apiname>Asic::Init3()</apiname></xref> function would
initialise the <codeph>ResourceManager</codeph> object, and set up <codeph>myResMgrPtr</codeph>.
Alternatively, if the Variant (or ASSP) were to need the resource manager
up and running, then you would initialise <codeph>ResourceManager</codeph> in <xref href="GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D.dita#GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D/GUID-63F2135B-4264-3B3B-9B68-656A89BF7EE9"><apiname>Asic::Init1()</apiname></xref>. </p>
<p>In this implementation, the Variant would export a header file(s) publishing
a list of controllable power resources. </p>
<section id="GUID-CC741BCC-D96E-4FB7-AA8C-7635D4131DE0"><title>Shared controllable
power resources</title> <p>Some controllable power resources can be shared
between groups of peripherals and therefore may require usage tracking. </p> <p>We
recommend that shared power resources be represented by a class derived from <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita"><apiname>MPowerInput</apiname></xref>.
This class offers the <codeph>Use()</codeph> and <codeph>Release()</codeph> interface
that encapsulates resource counting behaviour. This mechanism should turn
the resource on when the count becomes non-zero, and turn the resource off
when the count becomes zero. </p> <p>We suggest that your <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita"><apiname>MPowerInput</apiname></xref> derived
class defines and implements a <codeph>GetCount()</codeph> function that returns
the usage count on the shared resource. </p> </section>
<section id="GUID-37A4098A-5E44-5744-BCE1-CDC8B876E654"><title>A suggested
implementation of a resource manager</title> <p>While we have implied that
a resource manager is a single class, which we have called <codeph>ResourceManager</codeph>,
the resource manager is a notional concept for controlling power resources. <i>Symbian
neither mandates a format for a ResourceManager class, nor even its existence</i>.
In practice, it may be more useful to embed resource manager functions and
data in the Variant interface class (or the ASSP interface class, if appropriate). </p> <p>However,
for the purpose of explaining what a resource manager can do, it is easier
to assume that this behaviour is handled by a resource manager class. This
is the outline definition of such a class. </p> <codeblock id="GUID-BB326270-B8C6-5398-AB36-FA50011004CA" xml:space="preserve">class ResourceManager
    {
public:    
    void InitResources();                            // called by your Asic::Init3()/Asic::Init1()
    void Modify(TUint aSetMask, TUint aClrMask);    // only 32 simple Resources can be managed
    TBool GetResourceState(TUint aResBitMask);    // only 1 bit set on this mask, returns On/Off
public:
    (MPowerInput-derived) iSharedResource1;        // 1 per shared resource
    (MPowerInput-derived) iSharedResource2;
    ...
    };
      </codeblock> <p>The <codeph>InitResources()</codeph> function would
do at least two things: </p> <ul>
<li id="GUID-29FA1D5C-0691-5EB2-A45A-5925D5C58A56"><p>enable an appropriate
set of simple resources at boot time </p> </li>
<li id="GUID-6F0D4084-48E9-585B-857B-F67B7B453DC7"><p>initialise the shared
power resource tracking objects, i.e. the instances of your <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita"><apiname>MPowerInput</apiname></xref> derived
class(es). </p> </li>
</ul> <p>The function would be called by the Variant or ASSP implementation
of <xref href="GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D.dita#GUID-A83A7C3C-7DC0-3B9C-842F-70FCC751365D/GUID-FE55E398-7F08-384F-9E74-2CC2E45002B6"><apiname>Asic::Init3()</apiname></xref> or <xref href="GUID-21641835-7103-374B-9FBB-FAB1875D59A5.dita"><apiname>Asic:Init1()</apiname></xref>. </p> <p>The <codeph>Modify()</codeph> function
is an example of how to deal with power resources that are either on or off.
The function would take bit masks, where a bit represents a separate controllable
power resource. The first bit mask would represent the set of power resources
to be turned on, while the second would represent the set of power resources
to be turned off. This assumes that the function could behave synchronously.
Drivers for peripherals that use a set of these controllable power resources,
would call <codeph>Modify()</codeph> to turn the relevant controllable power
resources on or off. </p> <p>As an example, the most common method of switching
clock resources on or off is by setting and clearing bits in a hardware register.
A base port could choose to implement common code for setting bits in registers. </p> <p>A
shared power resource is further represented by a <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita"><apiname>MPowerInput</apiname></xref> derived
class. The implementations of <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita#GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A/GUID-2BCA5312-43D9-3763-9636-3B2EB046D2C1"><apiname>MPowerInput::Use()</apiname></xref> and <xref href="GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A.dita#GUID-10105403-AF16-3908-AE9E-96CF2A03AD3A/GUID-606ECD77-A5F7-3408-9B63-C68C0A7B73C6"><apiname>MPowerInput::Release()</apiname></xref> would
call <codeph>Modify()</codeph> to turn on the shared resource when the usage
count becomes non zero, or turn it off when the usage count reaches zero.
Peripheral drivers would have access to shared resources, and also to the
member functions of the <codeph>ResourceManager</codeph> class, through the
ASSP or Variant Interface class function that returns a pointer to it. </p> <p>The
resource manager, or its functions and members, could be offered as part of
a power controller interface class, the <codeph>TPowerController</codeph> class
suggested when we discussed the implementation of the <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita">Power
Controller</xref>'s <xref href="GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703.dita#GUID-34D1D0BF-20DE-5677-A067-8FF9DD72E703/GUID-5A0CAD08-AA12-56EE-B0A3-75548D1896C9">EnableWakeupEvents()</xref> function.
The class would provide an exported function that would give access to the
resource manager. The resource manager class would be made part of the power
controller kernel extension. Peripheral drivers needing access to shared power
resources would then link to the power controller DLL. If the Variant or ASSP
were also to need access to the resource manager, then the resource manager
would have to be initialised much earlier in the kernel start-up sequence.
In this case, we would suggest that the standard power controller kernel extension
entry point defined by <xref href="GUID-7964FC46-4641-3BDD-92C9-50FA22C3321A.dita"><apiname>DECLARE_STANDARD_EXTENSION()</apiname></xref> be
replaced with a custom entry point that might look like this: </p> <codeblock id="GUID-B5262624-C7B8-51E4-AE14-1D905DFC0A99" xml:space="preserve">GLDEF_C TInt KernelModuleEntry(TInt aReason)
    {
    if(aReason==KModuleEntryReasonVariantInit0)
        {
        ResourceManager* c = new ResourceManager ();    // create Resource Manager
        return c ? KErrNone : KErrNoMemory;    
        }
    else if(aReason==KModuleEntryReasonExtensionInit0)
        {
        (create DPowerController and Battery Monitor and Power HAL handler)
        }
    return KErrNone;         // gets here from calling with KModuleEntryReasonExtensionInit1
    }
        </codeblock> <p>The Variant or ASSP would also need to link to the
power controller DLL. </p> <p>The following base port software architecture
could be applied to the power supply arrangement as illustrated in the hardware
block diagram above (see the beginning of this section at <xref href="GUID-3B6544CD-FA6E-5AB2-AA63-61186F52167D.dita">Controllable
Power Resources</xref>): </p> <fig id="GUID-309A6C5E-A347-5E04-B2C8-426A81755226">
<title>Base port software architecture</title>
<image href="GUID-EE2F64B2-A2E3-524F-8E04-68BE9AA9EA36_d0e29378_href.png" placement="inline"/>
</fig> </section>
<section id="GUID-C4C67612-C5CD-5D64-B257-259FD12443C9"><title>Multi-level,
composite and asynchronous power resources</title> <p>Some power resources
may have more than one operational level. For example, it is possible that
an input clock to a peripheral can be operated at a nominal value corresponding
to the fully active state, and may be lowered to another level corresponding
to the power saving state. </p> <p>The same could apply to the input voltages
that the peripheral can operate on. The control model suggested above for
simple resources may not be appropriate. A suggested alternative would have
these multi-Level resources implementing an interface that offers a public
enumeration to cover all possible usage levels at which the resource can be
used, and APIs such as: </p> <codeblock id="GUID-44492A89-C7DC-5C97-928C-549BEAD38161" xml:space="preserve">class MultiLevelResource
    {
    enum TResourceLevel
        {
        EOperationalLevel1,
        EOperationalLevel2,
        . . .
        ELowPowerLevel1,
        ELowPowerLevel2,
        . . .
        };
    void UseToLevel();
    void ReleaseToLevel();
    TResourceLevel GetCurrentLevel();
    . . . 
    };</codeblock> <p>More importantly, it is possible that resources may
have to be operated in combination with other resources. For example, some
peripherals may have more than one input clock, and on transition between
power states, these clocks may have to be changed simultaneously. </p> <p>If
the resources to be actuated simultaneously are simple resources, then the
model above with a <codeph>Modify()</codeph> call that takes a bit mask and
allows more than one resource to be changed at a time may be appropriate.
If the resources to be actuated are shared or multi-level, or have to be represented
individually, then another interface will have to be defined to allow modifying
more than one of them simultaneously. </p> <p>Modifying some resources may
not be an instantaneous operation. For example, it may take a non-negligible
amount of time to stabilise an input clock that has just been modified. </p> <p>The
nature of EKA2 strongly discourages actively waiting (or “spinning”) inside
drivers; instead it is suggested that the multithreading capabilities of EKA2
kernel side code and the synchronisation mechanisms available be used to solve
the problem of having the driver code having to wait for a resource to stabilise
before proceeding with its use. </p> <p>As an example, let us assume that
the multi-level resource mentioned above has a non-negligible delay associated
with any level changes: </p> <ul>
<li id="GUID-0549E815-BB6E-55C7-84DB-FB6A2ACA11AC"><p>If the length of time
to wait for a power resource to stabilise is known, and is the order of a
few milliseconds or less, or the driver executes on its unique kernel thread
(not used by any other kernel-side code), then the best solution would be
to sleep the driver thread, by calling <codeph>NKern::Sleep(aTime)</codeph> for
the specified length of time after issuing a call to <codeph>UseToLevel()</codeph> (or <codeph>ReleaseToLevel()</codeph>). </p> </li>
<li id="GUID-9F0FCB9F-2827-528A-B3D0-FEE6CF8470CD"><p>When the length of time
to wait for a power resource to stabilise increases, then sleeping the driver
thread may become a problem if the driver executes in a DFC queue used by
other drivers, which is often the case. This is because blocking that thread
means that no other drivers can run. Here, the best solution is for the driver
to create another thread and DFC queue, by calling <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-B9D637A1-4EB9-39F7-8C5C-2C546994C4B8"><apiname>Kern::DfcQInit()</apiname></xref>,
and whenever it needs to change the resource, queue a DFC on that queue, which
will issue the calls to <codeph>UseToLevel()</codeph> (or <codeph>ReleaseToLevel()</codeph>)
and then sleep the thread. </p> </li>
<li id="GUID-C8472B27-FC27-5C72-B6C2-A0DA681EA3C6"><p>If the length of time
to change a power resource cannot be known in advance, but the hardware provides
an indication of completion of the change, for example, in the form of an
interrupt, then the solution may involve the driver code waiting on a Fast
Mutex, which is signalled by the completion event (in code belonging to the <codeph>MultiLevelResource</codeph> derived
object). </p> </li>
</ul> </section>
</conbody></concept>