7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept id="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9" xml:lang="en"><title>Porting |
12 <concept id="GUID-2ECF13A1-9D56-5740-A09F-8267E6A45DD9" xml:lang="en"><title>Porting the Power Resource Manager</title><shortdesc>This tutorial describes how to port the Platform Specific |
13 the Power Resource Manager</title><shortdesc>This tutorial describes how to port the Platform Specific Layer |
13 Layer (PSL) of the Power Resource Manager (<keyword>PRM</keyword>) |
14 (PSL) of the Power Resource Manager (<keyword>PRM</keyword>) and how to modify |
14 and how to modify clients, such as device drivers, to use the PRM |
15 clients, such as device drivers, to use the PRM framework.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
15 framework.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
16 <section id="GUID-97905214-40EC-44A1-95D6-7F2C1636C638"><title>Purpose</title> <p>The |
16 <section id="GUID-97905214-40EC-44A1-95D6-7F2C1636C638"><title>Purpose</title> <p>The PRM is a framework for managing system power resources. This |
17 PRM is a framework for managing system power resources. This framework improves |
17 framework improves portability across different platforms and reduces |
18 portability across different platforms and reduces device driver complexity. </p> <p>The |
18 device driver complexity. </p> <p>The PRM framework is split into |
19 PRM framework is split into two layers: </p> <ul> |
19 two layers: </p> <ul> |
20 <li id="GUID-17F4DFA5-2848-5CA9-BE5D-F7F52BB1705F"><p>Platform Independent |
20 <li id="GUID-17F4DFA5-2848-5CA9-BE5D-F7F52BB1705F"><p>Platform Independent |
21 Layer - the PIL is a generic software layer that is implemented by Symbian. |
21 Layer - the PIL is a generic software layer that is implemented by |
22 This is the base virtual class for the Power Resource Controller (<xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita"><apiname>DPowerResourceController</apiname></xref>), </p> </li> |
22 Symbian. This is the base virtual class for the Power Resource Controller |
23 <li id="GUID-B6499506-0B33-588F-BEFC-12A4D9FDF239"><p>Platform Specific Layer |
23 (<xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita"><apiname>DPowerResourceController</apiname></xref>), </p> </li> |
24 - the PSL is developed specifically to interface with the target hardware |
24 <li id="GUID-B6499506-0B33-588F-BEFC-12A4D9FDF239"><p>Platform Specific |
25 by licensees. This is the class derived from <codeph>DPowerResourceController</codeph>. </p> </li> |
25 Layer - the PSL is developed specifically to interface with the target |
|
26 hardware by licensees. This is the class derived from <codeph>DPowerResourceController</codeph>. </p> </li> |
26 </ul> <p>Other acronyms used in this document set: </p> <ul> |
27 </ul> <p>Other acronyms used in this document set: </p> <ul> |
27 <li id="GUID-ED8A465C-B8CB-5C7A-8D57-D207AAA41F89"><p>H4 HRP - OMAP2420 SDP |
28 <li id="GUID-ED8A465C-B8CB-5C7A-8D57-D207AAA41F89"><p>H4 HRP - OMAP2420 |
28 hardware reference platform referred to in these documents as examples of |
29 SDP hardware reference platform referred to in these documents as |
29 the base port, </p> </li> |
30 examples of the base port, </p> </li> |
30 <li id="GUID-97B58DBF-51DA-5982-A2D2-BF3453B062F2"><p>LDD - Logical Device |
31 <li id="GUID-97B58DBF-51DA-5982-A2D2-BF3453B062F2"><p>LDD - Logical |
31 Driver. The higher layer of abstraction within the Symbian platform device |
32 Device Driver. The higher layer of abstraction within the Symbian |
32 driver framework which implements common functionality among differing pieces |
33 platform device driver framework which implements common functionality |
33 of hardware of one type, </p> </li> |
34 among differing pieces of hardware of one type, </p> </li> |
34 <li id="GUID-547FA744-0D75-516A-954A-E9D1DBCBAC87"><p>PDD - Physical Device |
35 <li id="GUID-547FA744-0D75-516A-954A-E9D1DBCBAC87"><p>PDD - Physical |
35 Driver. The lower layer of abstraction within the Symbian platform device |
36 Device Driver. The lower layer of abstraction within the Symbian platform |
36 driver framework which implements functionality that is specific to a particular |
37 device driver framework which implements functionality that is specific |
37 piece of hardware. </p> </li> |
38 to a particular piece of hardware. </p> </li> |
38 </ul> <p><b>Intended audience</b> </p> <p>This document is intended to be |
39 </ul> <p><b>Intended audience</b> </p> <p>This document is intended |
39 used by Symbian platform device creators. </p> <p><b>Required background</b> </p> <p>The |
40 to be used by Symbian platform device creators. </p> <p><b>Required |
40 reader of this document is assumed to have knowledge of the Symbian platform |
41 background</b> </p> <p>The reader of this document is assumed to have |
41 device driver model and <keyword>base port</keyword> layering and components. </p> <ul> |
42 knowledge of the Symbian platform device driver model and <keyword>base port</keyword> layering and components. </p> <ul> |
42 <li id="GUID-611721D2-17C4-56F4-9101-6088B062BB2C"><p> <xref href="GUID-8D80AA51-5108-5D4B-B6B9-7FA47570AB89.dita">Device |
43 <li id="GUID-611721D2-17C4-56F4-9101-6088B062BB2C"><p> <xref href="GUID-8D80AA51-5108-5D4B-B6B9-7FA47570AB89.dita">Device Driver Concepts</xref>, </p> </li> |
43 Driver Concepts</xref>, </p> </li> |
44 <li id="GUID-938A492F-B9CB-5DFB-B382-2B7E6C5E3711"><p> <xref href="GUID-A7F6C8D5-B85B-537B-8A19-99149FBE8C01.dita">The core porting |
44 <li id="GUID-938A492F-B9CB-5DFB-B382-2B7E6C5E3711"><p> <xref href="GUID-A7F6C8D5-B85B-537B-8A19-99149FBE8C01.dita">The |
45 process</xref>. </p> </li> |
45 core porting process</xref>. </p> </li> |
46 </ul> <p>This document refers to the reference implementation of the |
46 </ul> <p>This document refers to the reference implementation of the PRM PSL |
47 PRM PSL for the H4 HRP platform wherever possible. The source code |
47 for the H4 HRP platform wherever possible. The source code for the reference |
48 for the reference implementation can be found in <filepath>\omap_hrp\h4\resman</filepath>. The MMC and Sound_SC (in H4 HRP) device drivers are modified to |
48 implementation can be found in <filepath>\omap_hrp\h4\resman</filepath>. The |
49 use the new PRM framework. </p> <p><b>Introduction</b> </p> <p>The |
49 MMC and Sound_SC (in H4 HRP) device drivers are modified to use the new PRM |
50 PRM provides a unique place where all the current power states for |
50 framework. </p> <p><b>Introduction</b> </p> <p>The PRM provides a unique place |
51 resources can be obtained at any time. The sum of all internal and |
51 where all the current power states for resources can be obtained at any time. |
52 external power states defines the current system-wide power state. </p> <p id="GUID-0F328055-DBCE-5B2B-A1EB-77F73BA1FC82"><b>Setup and configuration |
52 The sum of all internal and external power states defines the current system-wide |
53 requirements</b> </p> <p>The PRM component is implemented as a kernel |
53 power state. </p> <p id="GUID-0F328055-DBCE-5B2B-A1EB-77F73BA1FC82"><b>Setup |
54 extension with an exported public interface that is accessible to |
54 and configuration requirements</b> </p> <p>The PRM component is implemented |
55 kernel side components through statically linking against its export |
55 as a kernel extension with an exported public interface that is accessible |
56 library. The export library is built from the resource manager and |
56 to kernel side components through statically linking against its export library. |
57 the resource manager libraries. </p> <p>There are two versions available: </p> <ul> |
57 The export library is built from the resource manager and the resource manager |
58 <li id="GUID-982137EB-A7C2-5420-8279-477AC52D5350"><p>basic resource |
58 libraries. </p> <p>There are two versions available: </p> <ul> |
59 manager - provides essential or required functionality for static |
59 <li id="GUID-982137EB-A7C2-5420-8279-477AC52D5350"><p>basic resource manager |
60 resources. </p> <p>The basic version of the PIL layer is compiled |
60 - provides essential or required functionality for static resources. </p> <p>The |
61 into <filepath>resmanpsl.lib</filepath>. This kernel library must |
61 basic version of the PIL layer is compiled into <filepath>resmanpsl.lib</filepath>. |
62 be included by the PSL to produce the kernel extension. </p> </li> |
62 This kernel library must be included by the PSL to produce the kernel extension. </p> </li> |
63 <li id="GUID-0F8863B3-044C-5B5A-831D-DB20B72459C8"><p>extended resource |
63 <li id="GUID-0F8863B3-044C-5B5A-831D-DB20B72459C8"><p>extended resource manager |
64 manager - provides additional support for dynamic resources and resource |
64 - provides additional support for dynamic resources and resource dependencies. </p> <p>The |
65 dependencies. </p> <p>The extended version of the PIL layer is complied |
65 extended version of the PIL layer is complied into <filepath>resmanextenedpsl.lib</filepath>. |
66 into <filepath>resmanextenedpsl.lib</filepath>. This kernel library |
66 This kernel library must be included by the PSL to produce the kernel extension. </p> </li> |
67 must be included by the PSL to produce the kernel extension. </p> </li> |
67 </ul> <p>Device drivers that require the use of the PRM should link against |
68 </ul> <p>Device drivers that require the use of the PRM should link |
68 the appropriate library. <filepath>resman.lib</filepath> to use the basic |
69 against the appropriate library. <filepath>resman.lib</filepath> to |
69 version and <filepath>resmanextended.lib</filepath> to use the extended version |
70 use the basic version and <filepath>resmanextended.lib</filepath> to |
70 of the PRM. </p> <p><b>Building the PRM for the target platform</b> </p> <p>The |
71 use the extended version of the PRM. </p> <p><b>Building the PRM for |
71 PRM is an early extension, so the <xref href="GUID-9535CF67-7541-554E-BE5C-9FDDFDB58EA5.dita">targettype</xref> in |
72 the target platform</b> </p> <p>The PRM is an early extension, so |
72 the <keyword>mmp</keyword> file must be set to <codeph>kext</codeph>. If the |
73 the <codeph>targettype</codeph> in the <keyword>mmp</keyword> file |
73 PRM is implemented as a PDD the <codeph>targettype</codeph> in the mmp file |
74 must be set to <codeph>kext</codeph>. If the PRM is implemented as |
74 should be should be <codeph>pdd</codeph>. </p> <p><b>Boot sequence</b> </p> <p>The |
75 a PDD the <codeph>targettype</codeph> in the mmp file should be should |
75 PRM cannot be used to operate on power resources until later in the boot sequence |
76 be <codeph>pdd</codeph>. </p> <p><b>Boot sequence</b> </p> <p>The PRM cannot be used to operate on power resources until |
76 when the kernel allows the scheduling of other threads. During this time it |
77 later in the boot sequence when the kernel allows the scheduling of |
77 is not possible to read or change the state of resources, but <xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita#GUID-46F2174F-0206-345B-8C5D-F8B5763652E0/GUID-9D07A9C1-C0AE-36E9-8438-3BF71D3CBB0C"><apiname>DPowerResourceController::PostBootLevel()</apiname></xref> can |
78 other threads. During this time it is not possible to read or change |
78 be used to specify the state of specific resources and the PRM can change |
79 the state of resources, but <xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita#GUID-46F2174F-0206-345B-8C5D-F8B5763652E0/GUID-9D07A9C1-C0AE-36E9-8438-3BF71D3CBB0C"><apiname>DPowerResourceController::PostBootLevel()</apiname></xref> can be used to specify the state of specific resources and the PRM |
79 the state of resources to appropriate levels before the PRM is fully initialised. </p> <p> <codeph>PostBootLevel()</codeph> is |
80 can change the state of resources to appropriate levels before the |
80 used within the extension entry point, during this time PRM is not fully initialised. <b>Note</b>: |
81 PRM is fully initialised. </p> <p> <codeph>PostBootLevel()</codeph> is used within the extension entry point, during this time PRM is |
81 This function can only be used for static resources and static resources with |
82 not fully initialised. <b>Note</b>: This function can only be used |
82 dependencies. </p> <codeblock id="GUID-F8E2125A-0DA8-5991-8FED-BF6DA48EC79D" xml:space="preserve">static TInt PostBootLevel(TUint aResId, TInt aLevel);</codeblock> <p> <codeph>PostBootLevel()</codeph> takes the resource ID and the post boot |
83 for static resources and static resources with dependencies. </p> <codeblock id="GUID-F8E2125A-0DA8-5991-8FED-BF6DA48EC79D" xml:space="preserve">static TInt PostBootLevel(TUint aResId, TInt aLevel);</codeblock> <p> <codeph>PostBootLevel()</codeph> takes the resource ID and the |
83 level that the level a resource needs to be after it is initialised. Typically |
84 post boot level that the level a resource needs to be after it is |
84 the post boot level is only known to the PSL. However kernel extensions (and |
85 initialised. Typically the post boot level is only known to the PSL. |
85 the variant) may request a post boot level. </p> <p>If a kernel extension |
86 However kernel extensions (and the variant) may request a post boot |
86 needs to know if certain resources have reached the post boot state in order |
87 level. </p> <p>If a kernel extension needs to know if certain resources |
87 to complete its own initialisation then the kernel extension should queue |
88 have reached the post boot state in order to complete its own initialisation |
88 resource state change notifications for the resource when first registering |
89 then the kernel extension should queue resource state change notifications |
89 as clients with the PRM. <b>Note</b>: notification requests are accepted before |
90 for the resource when first registering as clients with the PRM. <b>Note</b>: notification requests are accepted before the PRM is fully |
90 the PRM is fully initialised. </p> <p>Variants or kernel extensions can register |
91 initialised. </p> <p>Variants or kernel extensions can register static |
91 static resources before the PRM is fully initialised with <xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita#GUID-46F2174F-0206-345B-8C5D-F8B5763652E0/GUID-6F74C10F-5055-37D2-968D-FCAB7D0F8FDF"><apiname>DPowerResourceController::RegisterStaticResource()</apiname></xref>. |
92 resources before the PRM is fully initialised with <xref href="GUID-46F2174F-0206-345B-8C5D-F8B5763652E0.dita#GUID-46F2174F-0206-345B-8C5D-F8B5763652E0/GUID-6F74C10F-5055-37D2-968D-FCAB7D0F8FDF"><apiname>DPowerResourceController::RegisterStaticResource()</apiname></xref>. This API can only be used by static resources and not by static |
92 This API can only be used by static resources and not by static resource that |
93 resource that support dependency. See <xref href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita#GUID-66FD040B-133E-57CF-80DD-9369F62709C6/GUID-61471315-14E1-5A0F-A164-92CF928C3604">DoRegisterStaticResources()</xref>. </p> </section> |
93 support dependency. See <xref href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita#GUID-66FD040B-133E-57CF-80DD-9369F62709C6/GUID-61471315-14E1-5A0F-A164-92CF928C3604">DoRegisterStaticResources()</xref>. </p> </section> |
94 <section id="GUID-EBBEF707-27E5-4E10-ADCA-A02C119EB075"><title>Using |
94 <section id="GUID-EBBEF707-27E5-4E10-ADCA-A02C119EB075"><title>Using the Power |
95 the Power Resource Manager</title> <p>Porting the PRM consists of |
95 Resource Manager</title> <p>Porting the PRM consists of implementing the PSL |
96 implementing the PSL layer for a given hardware platform and modifying |
96 layer for a given hardware platform and modifying clients, such as device |
97 clients, such as device drivers, to use the PRM framework. </p> <p>The following tasks are covered in this tutorial: </p> <ul> |
97 drivers, to use the PRM framework. </p> <p>The following tasks are covered |
98 <li id="GUID-21093CEB-845E-528F-81DF-BD21084E3A27"><p> <xref href="GUID-B1CE51BC-B452-5FC9-9C00-35447AF40671.dita"> Implement the controllable |
98 in this tutorial: </p> <ul> |
99 power resources</xref>, </p> </li> |
99 <li id="GUID-21093CEB-845E-528F-81DF-BD21084E3A27"><p> <xref href="GUID-B1CE51BC-B452-5FC9-9C00-35447AF40671.dita"> Implement |
100 <li id="GUID-93B8B5A9-D7EE-56A0-B96B-BA2FC8DE1CE7"><p> <xref href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita"> Implement the PSL |
100 the controllable power resources</xref>, </p> </li> |
101 for the target</xref>, </p> </li> |
101 <li id="GUID-93B8B5A9-D7EE-56A0-B96B-BA2FC8DE1CE7"><p> <xref href="GUID-66FD040B-133E-57CF-80DD-9369F62709C6.dita"> Implement |
102 <li id="GUID-417CE38C-66CC-5186-B833-B1A6E8CE21B8"><p> <xref href="GUID-E7F91A65-235D-589C-9A8C-0B207D19A24B.dita"> Port the client |
102 the PSL for the target</xref>, </p> </li> |
103 drivers to use the PRM</xref> (to control the implemented resources), </p> </li> |
103 <li id="GUID-417CE38C-66CC-5186-B833-B1A6E8CE21B8"><p> <xref href="GUID-E7F91A65-235D-589C-9A8C-0B207D19A24B.dita"> Port |
104 <li id="GUID-1420B749-8618-5FF3-93E3-F1A5E4579061"><p> <xref href="GUID-C8DF0CB0-92F4-5F9E-A8F1-7DE50954C4F1.dita">Debugging the PRM</xref>, </p> </li> |
104 the client drivers to use the PRM</xref> (to control the implemented resources), </p> </li> |
105 <li id="GUID-4EEEC53B-C162-5E3F-B047-ABD4951F9C46"><p> <xref href="GUID-66E5F769-1156-54CA-94BC-8912159A1240.dita"> Testing the PRM |
105 <li id="GUID-1420B749-8618-5FF3-93E3-F1A5E4579061"><p> <xref href="GUID-C8DF0CB0-92F4-5F9E-A8F1-7DE50954C4F1.dita">Debugging |
106 PSL</xref>. </p> </li> |
106 the PRM</xref>, </p> </li> |
|
107 <li id="GUID-4EEEC53B-C162-5E3F-B047-ABD4951F9C46"><p> <xref href="GUID-66E5F769-1156-54CA-94BC-8912159A1240.dita"> Testing |
|
108 the PRM PSL</xref>. </p> </li> |
|
109 </ul> </section> |
107 </ul> </section> |
110 </conbody><related-links> |
108 </conbody><related-links> |
111 <link href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita"><linktext>Power Resource |
109 <link href="GUID-6E1DE1E4-1B09-541C-8708-9126E69B42CE.dita"><linktext>Power |
112 Manager (PRM)</linktext></link> |
110 Resource Manager (PRM)</linktext></link> |
113 <link href="GUID-3773A78D-F491-52EB-AA1D-201636497F28.dita"><linktext>Power Management |
111 <link href="GUID-3773A78D-F491-52EB-AA1D-201636497F28.dita"><linktext>Power |
114 Tutorials</linktext></link> |
112 Management Tutorials</linktext></link> |
115 </related-links></concept> |
113 </related-links></concept> |