|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-54042C84-6216-5930-9CBF-BAF635CECD4D" xml:lang="en"><title>Power |
|
13 HAL Handler Tutorial</title><shortdesc>User-side programs can get and set a number of system attributes |
|
14 about power using the <codeph>HAL</codeph> interface. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>The base port must provide and register a HAL handler to handle these attributes. </p> |
|
16 <p>The power attributes are in the <xref href="GUID-FB85CE22-DDFF-37E6-A6CE-7F70A994D371.dita"><apiname>EHalGroupPower</apiname></xref> HAL group. |
|
17 The handler provides a kernel-side implementation to deal with the user-side |
|
18 calls to <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> and <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-9454F1B2-D525-3D6D-A872-C6457CACD4FC"><apiname>HAL::Set()</apiname></xref> when |
|
19 one of the following parameters is passed: </p> |
|
20 <ul> |
|
21 <li id="GUID-9AEBA9C2-BF3C-541D-BFD0-4E610DBE80A3"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-7344DA81-987E-351E-9F91-7AA78C3FA033"><apiname>HALData::EPowerGood</apiname></xref> </p> </li> |
|
22 <li id="GUID-5F3A4C2B-941F-5D57-8B43-EC451D840854"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-C7DDA0E9-5882-3988-8747-AA790AC31E05"><apiname>HALData::EPowerBatteryStatus</apiname></xref> </p> </li> |
|
23 <li id="GUID-0D50D9CD-8AE9-5831-8E80-EE8B5230907D"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-6A6650DE-67C1-3E1E-AFC7-CA7ADCED621D"><apiname>HALData::EAccessoryPower</apiname></xref> </p> </li> |
|
24 <li id="GUID-06A8A38B-3F3F-5B41-B79F-57CD49ABC382"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-5800E3AA-61A7-33B1-BBAE-6E4D826373AB"><apiname>HALData::EPowerBackup</apiname></xref> </p> </li> |
|
25 <li id="GUID-77277657-3765-531B-8E19-8D2E11BAA558"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-C6E1EDDD-06C4-3A4D-9C93-67316D6C4823"><apiname>HALData::EPowerBackupStatus</apiname></xref> </p> </li> |
|
26 <li id="GUID-9179DF67-5AFC-5C98-ACFD-391035A32756"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-435EB49C-8821-37DD-8D13-46158B6261BD"><apiname>HALData::EPowerExternal</apiname></xref> </p> </li> |
|
27 <li id="GUID-E10E8676-5DB4-5045-9BDC-DF280695A4C6"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-079CD0A7-6C36-3A05-8EFA-51FDD649C657"><apiname>HALData::EPenDisplayOn</apiname></xref> </p> </li> |
|
28 <li id="GUID-81581675-F4E7-517C-BF25-22CDCC87E787"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-A0F07710-1C15-3B7F-8D45-02D9E40A2514"><apiname>HALData::ECaseSwitchDisplayOn</apiname></xref> </p> </li> |
|
29 <li id="GUID-D9DC5061-371E-5B89-8CA5-93FA99B7827A"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-148D0CDF-6CEC-33BD-876A-CA93D0C702B3"><apiname>HALData::ECaseSwitchDisplayOff</apiname></xref> </p> </li> |
|
30 </ul> |
|
31 <p>A typical application will have a user side monitor that periodically calls <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref>, |
|
32 passing <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-C7DDA0E9-5882-3988-8747-AA790AC31E05"><apiname>HALData::EPowerBatteryStatus</apiname></xref> to get the charge |
|
33 level of the battery. </p> |
|
34 <p>Typically, the handler is implemented as part of a <xref href="GUID-3E6D44FE-787B-3D9E-899C-8BAA7DDCBC5C.dita"><apiname>DPowerHal</apiname></xref> derived |
|
35 object, which is created by the entry point of the base port power kernel |
|
36 extension. The object is, therefore, part of the power controller kernel extension. </p> |
|
37 <section id="GUID-292B08F7-9BE6-4D85-A70E-A063D300195F"><title>Implementation |
|
38 notes</title> <ul> |
|
39 <li id="GUID-A69AD521-6B9C-565F-944F-125774283041"><p>The <xref href="GUID-3E6D44FE-787B-3D9E-899C-8BAA7DDCBC5C.dita"><apiname>DPowerHal</apiname></xref> derived |
|
40 object constructor must register with the power manager by calling <codeph>Register()</codeph>. </p> </li> |
|
41 <li id="GUID-5E2558D9-DB44-554A-8A18-33D161E568D2"><p>If there is some power-related |
|
42 data that can be accessed via the HAL component and that persists through |
|
43 power cycles (On/Off), it should be initialised here. Typically the <codeph>TOnOffInfoV1</codeph> data |
|
44 member of the Variant-specific <codeph>TActualMachineConfig</codeph> (usually |
|
45 found in <filepath>mconf.h</filepath> file under the platform directory) contains |
|
46 some of that persistent data. </p> </li> |
|
47 <li id="GUID-07E132AF-0F18-5578-A74C-C87618F98678"><p>The handler itself is |
|
48 the function <codeph>PowerHalFunction()</codeph>, and must be fully implemented |
|
49 in the base port. </p> </li> |
|
50 <li id="GUID-EEB6EB2D-8E99-5EFF-B2C6-4C73E6D39852"><p>The kernel hooks up |
|
51 the handler to service the HAL functions at boot-time. </p> </li> |
|
52 <li id="GUID-6C2DE544-5447-5786-8F0C-A065E0C1A59A"><p>The power Hal functions |
|
53 that the Handler can handle are enumerated by <xref href="GUID-105D7978-FFAD-3868-BE6A-8A9746A82D70.dita"><apiname>TPowerHalFunction</apiname></xref>. |
|
54 Not all of these functions need to be handled. If not handled, the kernel |
|
55 returns <codeph>KErrNotSupported</codeph> when the HAL function is called |
|
56 with the relevant parameter. It is left to the base port to decide which functions |
|
57 are relevant. </p> </li> |
|
58 </ul> </section> |
|
59 </conbody><related-links> |
|
60 <link href="GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita#GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8/GUID-4DA41221-40B9-5BC7-B2C6-7C6EB4522508"> |
|
61 <linktext>User-Side Hardware Abstraction</linktext></link> |
|
62 </related-links></concept> |