author | Graeme Price <GRAEME.PRICE@NOKIA.COM> |
Fri, 15 Oct 2010 14:32:18 +0100 | |
changeset 15 | 307f4279f433 |
permissions | -rw-r--r-- |
15
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
1 |
<?xml version="1.0" encoding="utf-8"?> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
2 |
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
3 |
<!-- This component and the accompanying materials are made available under the terms of the License |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
4 |
"Eclipse Public License v1.0" which accompanies this distribution, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
5 |
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
6 |
<!-- Initial Contributors: |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
7 |
Nokia Corporation - initial contribution. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
8 |
Contributors: |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
9 |
--> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
10 |
<!DOCTYPE concept |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
11 |
PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
12 |
<concept id="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413" xml:lang="en"><title>User-Side |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
13 |
Hardware Abstraction Technology</title><shortdesc>Description of HAL types and interfaces.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
14 |
<p>The User-Side Hardware Abstraction (HAL) component provides a platform-independent |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
15 |
way to access and control many device specific features, and to hide hardware-specific |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
16 |
functionality. For example, HAL can be used to find out if a screen backlight |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
17 |
is present or not, or to set the display contrast. This topic </p> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
18 |
<section id="GUID-174A663C-3943-5D36-B507-D97A687C168C"><title>Attributes</title> <p>Specific |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
19 |
items of hardware related information are referred to as <i>attributes</i>. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
20 |
Symbian platform defines two types of attribute: </p> <ul> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
21 |
<li id="GUID-3A220CC5-7D56-5FB8-A69A-EFAAC0159561"><p>Non-derived attribute. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
22 |
This is an attribute where the information it represent is simply a value |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
23 |
that is stored in, and retrieved from, the HAL. </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
24 |
<li id="GUID-934EFFE7-4768-5919-8900-6DE6915E3195"><p>Derived attribute. This |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
25 |
is an attribute that requires a software call to obtain and set its value. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
26 |
The software component is, ultimately provided by a driver, kernel extension |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
27 |
or by the kernel itself. The drivers or kernel extensions normally need porting. </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
28 |
</ul> <p>Attributes are identified by the enumeration values of the enumerator <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-1959915A-BA99-3F94-AFD4-FD1AA540BFBF"><apiname>HALData::TAttribute</apiname></xref> defined |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
29 |
in <filepath>...\hal\inc\hal_data.h</filepath> and is exported to <filepath>...\epoc32\include\</filepath>. </p> <p>To |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
30 |
maintain backwards compatibility, the numbers identifying HAL attributes are |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
31 |
allocated strictly increasing consecutive values, and that a given HAL attribute |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
32 |
always has the same enumeration number on all implementations of Symbian platform. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
33 |
This means that new HAL attributes can only be added by Symbian. This also |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
34 |
means that the addition of custom HAL attributes is not possible. </p> </section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
35 |
<section id="GUID-F1F21DDA-DEA0-502E-83DB-84DDCFA5CBF8"><title>User-side interface</title> <p>Symbian |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
36 |
platform provides the following static functions to get and set information |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
37 |
about specific hardware features: </p> <ul> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
38 |
<li id="GUID-75ADEAE6-3BA5-55AA-9F6D-B91491CD1B7B"><p> <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> </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
39 |
<li id="GUID-A11EFEFE-D480-5557-965E-FEC524B7C5A9"><p> <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> </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
40 |
<li id="GUID-CD26D10D-84EB-56D4-AC70-86C2E65734E6"><p> <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-EF03B832-E9AA-32CF-903F-DFFA63A3E9AB"><apiname>HAL::GetAll()</apiname></xref> </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
41 |
</ul> <p>The <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita"><apiname>HAL</apiname></xref> class is defined in the source tree header |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
42 |
file <filepath>...\hal\inc\hal.h</filepath>, and is exported to <filepath>...\epoc32\include\</filepath>. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
43 |
The functions are exported from the HAL DLL, which is built as part of the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
44 |
Variant. </p> <p> <codeph>Get()</codeph> and <codeph>Set()</codeph> take an <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-174A663C-3943-5D36-B507-D97A687C168C">attribute</xref> to |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
45 |
identify specific hardware functionality. </p> <p> <codeph>GetAll()</codeph>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
46 |
as its name implies gets all available hardware information, but is rarely |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
47 |
used. See <xref href="GUID-124AC7EE-E227-5358-A755-628FFE257250.dita#GUID-124AC7EE-E227-5358-A755-628FFE257250/GUID-D75D3A65-590D-5716-84A7-0195DFCD1656">Dealing |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
48 |
with the HAL::GetAll() function</xref> for more information. </p> <p> <codeph>Get()</codeph> and <codeph>Set()</codeph> each |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
49 |
have a variation that allows a device number to be specified. The device number |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
50 |
allows more than one set of attributes to be used. Each set is associated |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
51 |
with a different device number. This is motivated by the need to support multiple |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
52 |
display screens where each screen is identified as a separate device of the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
53 |
same 'type'. The idea of a device can be extended other hardware, and indeed |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
54 |
the underlying implementation assumes a device number. If a device number |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
55 |
is not specified and has no meaning, then a default device number of 0 is |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
56 |
assumed for compatibility with the underlying implementation. </p> <p>For |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
57 |
example, on return from code such as: </p> <codeblock id="GUID-D512D36F-C94A-50C2-9245-569C6386E559" xml:space="preserve">... |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
58 |
TInt xpixels; |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
59 |
HAL::Get(EDisplayXPixels, xpixels); |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
60 |
...</codeblock> <p> <codeph> xpixels</codeph> contains the horizontal size |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
61 |
of the display screen in terms of the number of pixels. If you have more than |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
62 |
one screen, i.e. more than one device, then you would use the API variant |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
63 |
that takes a device number. </p> </section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
64 |
<section id="GUID-79BE4534-B9C6-5D64-8CB0-E3EEDE8AD293"><title>HAL handler |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
65 |
interface</title> <p>A request for fetching and setting information about |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
66 |
hardware is dealt with by an entity called a HAL handler on the kernel side. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
67 |
This section describes the types and concepts used to implement a HAL handler. </p> </section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
68 |
<section id="GUID-FBA183CB-E9D5-4E70-B65F-A496853D614B"><title>HAL groups and function-ids</title><p>It is useful to group |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
69 |
together requests for information about related hardware features so that |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
70 |
they can be dealt with by a single HAL handler. As an example, all the HAL |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
71 |
screen attributes are in the display group and are handled by the screen (i.e. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
72 |
video or LCD) driver. This means that a HAL group has a one-to-one association |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
73 |
with a HAL handler. </p> <p>A HAL group has an associated set of function-ids, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
74 |
which identify requests for different pieces of information to the HAL handler. </p> <p>Symbian |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
75 |
platform identifies HAL groups by a number defined by the <xref href="GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7.dita"><apiname>THalFunctionGroup</apiname></xref> enum |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
76 |
in <filepath>u32hal.h</filepath>, which is exported to <filepath>...\epoc32\include</filepath>. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
77 |
For example, the <xref href="GUID-7F299BFC-D8A5-3A5A-B8DA-39BF42C99DC6.dita"><apiname>EHalGroupDisplay</apiname></xref> enum value identifies |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
78 |
the group associated with the HAL screen attributes. </p> <p>The function-ids |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
79 |
associated with each HAL group are also defined in <filepath>u32hal.h</filepath>. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
80 |
Each set of function-ids is defined by an enum; for example the enum <xref href="GUID-BB011D9B-105F-345C-9FC0-39B0BA509394.dita"><apiname>TDisplayHalFunction</apiname></xref> defines |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
81 |
the function-ids associated with the HAL group <xref href="GUID-7F299BFC-D8A5-3A5A-B8DA-39BF42C99DC6.dita"><apiname>EHalGroupDisplay</apiname></xref>. </p> <p>The |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
82 |
idea of the HAL group is what allows HAL handling functionality to be implemented |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
83 |
in the Variant, rather than in the kernel. </p> <p>Up to 32 groups can be |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
84 |
defined. Often, a HAL group is concerned with mode settings for a particular |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
85 |
piece of hardware; for example there are standard HAL groups for keyboard, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
86 |
digitiser and display. However, some groups are concerned with some overall |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
87 |
aspect of the platform which extends across all devices; for example, there |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
88 |
is a group to handle emulation parameters on emulator platforms. </p> <p>An <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-174A663C-3943-5D36-B507-D97A687C168C">attribute</xref> maps |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
89 |
to a HAL group/function-id pair, although the mapping is not necessarily a |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
90 |
one-to-one relationship. For example, the calls: </p> <codeblock id="GUID-FB9CB26C-3DEF-5E8B-A564-40ECC68AD2FD" xml:space="preserve">TInt xPixels, yPixels; |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
91 |
... |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
92 |
HAL::Get(HALData::EDisplayXPixels,xPixels); |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
93 |
HAL::Get(HALData::EDisplayYPixels,yPixels); |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
94 |
...</codeblock> <p>both result in calls to the screen (i.e. video or LCD) |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
95 |
HAL handler, as represented by the HAL group number <xref href="GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7.dita#GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7/GUID-950EA0D3-747F-305E-92EA-1579023A111E"><apiname>THalFunctionGroup::EHalGroupDisplay</apiname></xref>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
96 |
using the same function-id <xref href="GUID-BB011D9B-105F-345C-9FC0-39B0BA509394.dita#GUID-BB011D9B-105F-345C-9FC0-39B0BA509394/GUID-FD814550-9B59-3196-827C-5C1A87E09D77"><apiname>TDisplayHalFunction::EDisplayHalScreenInfo</apiname></xref>. </p> <p>However, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
97 |
there are HAL group/function-id pairs for which there are no corresponding |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
98 |
generic attributes. In these cases, the hardware attributes represented by |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
99 |
the HAL group/function-id pair are used internally, and can only be accessed |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
100 |
using the kernel side function <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-DA115709-A225-3E2A-BCCD-6E2BB15979B9"><apiname>Kern::HalFunction()</apiname></xref> **. </p> <p>The |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
101 |
following picture shows the general idea: </p> <fig id="GUID-95743ED4-8CEC-5BAD-A5C2-9FD16D0485FA"> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
102 |
<image href="GUID-F50E1C81-E80F-5692-996B-3AC2BE995425_d0e39862_href.png" placement="inline"/> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
103 |
</fig> <p>**Technically, the user side function <codeph>UserSvr::HalFunction()</codeph> will |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
104 |
achieve the same thing, but this is <i>internal to Symbian</i> and is <i>not |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
105 |
intended for general use</i>. </p></section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
106 |
<section id="GUID-F28BA77B-D7AA-4D27-8ADF-029F42F800E4"><title>HAL handler implementation</title><p>Most HAL handlers are |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
107 |
implemented as part of a driver, a kernel extension, the Variant or the kernel |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
108 |
itself. Some will need porting. See <xref href="GUID-857F981E-711B-5CA8-AB37-5C700A6140FA.dita">Groups |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
109 |
and the location of their HAL handlers</xref>. </p> <p>An extension or a device |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
110 |
driver <i>must register</i> a handler for HAL group. It does so by calling <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-8C8DCE9D-0094-3909-8FDA-2F3134D0BC88"><apiname>Kern::AddHalEntry()</apiname></xref>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
111 |
specifying the group number. It is important to note that it is the extension |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
112 |
or driver's responsibility to do this; in other words, the kernel cannot know |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
113 |
what entity within a final ported Symbian platform is going to be the HAL |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
114 |
handler until it is explicitly told by registration. One point to note is |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
115 |
that the HAL handlers for the groups: <xref href="GUID-F10DCE1F-756C-318D-B0D1-8C8F5255959E.dita"><apiname>EHalGroupKernel</apiname></xref>, <xref href="GUID-D60C5503-A176-354A-A655-22BE371178AE.dita"><apiname>EHalGroupVariant</apiname></xref> and <xref href="GUID-FB85CE22-DDFF-37E6-A6CE-7F70A994D371.dita"><apiname>EHalGroupPower</apiname></xref> are not explicitly registered - they are registered internally by the kernel |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
116 |
itself. </p> <p>Internally, pointers to the HAL handler are stored in the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
117 |
array <codeph>K::HalFunction[]</codeph>, and this is indexed by the group |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
118 |
number. </p> <p>On the template board, for example, the HAL handler for the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
119 |
display group is part of the screen driver. The screen driver source can be |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
120 |
found in <filepath>...\template_variant\specific\lcd.cpp</filepath>. The HAL |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
121 |
handler itself is the function: </p> <codeblock id="GUID-C7272D10-F603-5DF6-8C0B-EE18EDDAF32E" xml:space="preserve">LOCAL_C TInt halFunction(TAny* aPtr, TInt aFunction, TAny* a1, TAny* a2) |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
122 |
{ |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
123 |
DLcdPowerHandler* pH=(DLcdPowerHandler*)aPtr; |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
124 |
return pH->HalFunction(aFunction,a1,a2); |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
125 |
}</codeblock> <p>The following code, implemented in the Create() function |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
126 |
of the main class, does the registration. </p> <codeblock id="GUID-2B8BFFC5-8FC5-5220-BE9D-F02003C41275" xml:space="preserve">TInt DLcdPowerHandler::Create() |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
127 |
{ |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
128 |
... |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
129 |
// install the HAL function |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
130 |
r=Kern::AddHalEntry(EHalGroupDisplay,halFunction,this); |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
131 |
if (r!=KErrNone) |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
132 |
return r; |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
133 |
... |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
134 |
}</codeblock> <p>Security is the responsibility of the HAL handler. If |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
135 |
necessary, it needs to check the capability of the caller's process. Each |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
136 |
information item, as identified by the function-id, can have an associated |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
137 |
capability. </p> <p>Each function-id defined in <filepath>u32hal.h</filepath> is |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
138 |
documented with the required capability. If no capability is listed, then |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
139 |
no specific capability is required. </p> <p>See <xref href="GUID-124AC7EE-E227-5358-A755-628FFE257250.dita">Implementing |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
140 |
HAL handlers</xref> for details. </p> </section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
141 |
<section id="GUID-042A8840-2260-5951-8951-E6E2A83F378E"><title>Kernel-side |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
142 |
interface</title> <p>Code such as device drivers that runs on the kernel side |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
143 |
need not use the generic interface provided by the HAL class functions. The <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-DA115709-A225-3E2A-BCCD-6E2BB15979B9"><apiname>Kern::HalFunction()</apiname></xref> API |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
144 |
is provided to access HAL information. </p> <p>Unlike the HAL class functions, <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-DA115709-A225-3E2A-BCCD-6E2BB15979B9"><apiname>Kern::HalFunction()</apiname></xref> uses |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
145 |
the group number and function-ids to identify hardware related information. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
146 |
This means that kernel side code does not use attributes to identify hardware |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
147 |
related information. The implication here is that you <i>may</i> have to make |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
148 |
changes to your kernel side code when porting to another platform. In practice, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
149 |
no changes may be needed, but at the very least you need to check. </p> </section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
150 |
<section id="GUID-43324161-56E6-40A7-A4C4-D3D8435D3568"><title>Config and Values files define attributes</title><p>Although |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
151 |
an <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-174A663C-3943-5D36-B507-D97A687C168C">attribute</xref> is |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
152 |
generic, some attributes may not have meaning on some platforms. In addition, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
153 |
each platform needs to define whether an attribute is either: </p> <ul> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
154 |
<li id="GUID-5D6B46DF-FAE7-5097-832D-F8FD33A3DB53"><p> <i>non-derived</i>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
155 |
i.e. has a value that is simply stored in the HAL, </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
156 |
</ul> <p>or: </p> <ul> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
157 |
<li id="GUID-B40D5AE3-13E7-50B0-8926-5B3461496DD2"><p> <i>derived</i>, i.e. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
158 |
requires a call to a software entity to get and set the value. </p> </li> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
159 |
</ul> <p>This is the role of the <i>Config file</i>. </p> <p>The Config file |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
160 |
contains a list of all the attributes that have meaning on a platform, and |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
161 |
uses the symbols defined in the enum <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-1959915A-BA99-3F94-AFD4-FD1AA540BFBF"><apiname>HALData::TAttribute</apiname></xref> to |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
162 |
identify them. Using a simple syntax, an attribute can be defined as being |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
163 |
derived by associating the attribute symbol with the name of a function. This |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
164 |
function is known as the <i>accessor function</i>. </p> <p>There is also a |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
165 |
file known as the <i>Values file</i> that defines the initial values for all |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
166 |
of the non-derived attributes, i.e. those attributes that are simply stored |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
167 |
in, and retrieved from, the HAL. </p> <p>The Config and Values files are text |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
168 |
files that, for a specific implementation of the HAL, reside in the <filepath>...\variant\hal</filepath> directory. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
169 |
The MMP file also resides there, and the HAL is built as part of the Variant. |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
170 |
As part of the build process, the Config and Values files are passed to a |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
171 |
Perl script, <filepath>halcfg.pl</filepath>, which translates the contents |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
172 |
into C++ source files. The resulting binaries are linked in as part of the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
173 |
resulting HAL DLL. </p> <p>In effect, these C++ source files implement the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
174 |
static data arrays defined by the <codeph>HalInternal</codeph> class. As its |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
175 |
name suggests, <b>this class is internal to Symbian platform</b>, and is only |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
176 |
discussed here to help with understanding. </p> <codeblock id="GUID-35660653-5519-59B9-A8D1-1BC18EA5E46D" xml:space="preserve">class HalInternal |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
177 |
{ |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
178 |
... |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
179 |
static const TUint8 Properties[HAL::ENumHalAttributes]; |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
180 |
... |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
181 |
static const TInt InitialValue[HAL::ENumHalAttributes]; |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
182 |
static const THalImplementation Implementation[HAL::ENumHalAttributes]; |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
183 |
... |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
184 |
}</codeblock> <p>The data member <codeph>Implementation[]</codeph> is |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
185 |
an array of pointers to the accessor functions </p> <p>See <xref href="GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita">Creating |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
186 |
the Config & Values files</xref> for detailed syntax. </p></section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
187 |
<section id="GUID-35FF9B50-7503-4F8E-B7A7-91287FDB57AB"><title>Derived attributes require accessor functions</title><p>Each |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
188 |
derived attribute has a corresponding accessor function. For example, <codeph>ProcessDisplayContrast()</codeph>. </p> <p>All |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
189 |
accessor functions are implemented in <filepath>...\hal\src\userhal.cpp</filepath>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
190 |
and are provided by Symbian platform because of the 'connection' to attributes |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
191 |
which are themselves defined as part of the generic platform. </p> <p>Generally |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
192 |
there is one accessor function per derived attribute, although there is nothing |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
193 |
to prevent an accessor function dealing with more than one attribute. The |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
194 |
attribute number is used to route calls made 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> forward |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
195 |
to the correct accessor function. Internally, Symbian platform routes calls |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
196 |
to Get() and Set() for an attribute to the same accessor function, distinguishing |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
197 |
between the two by a boolean value. </p> <p>A new implementation of an accessor |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
198 |
function should rarely, if ever, be needed as all likely accessor functions |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
199 |
are already defined and implemented by Symbian platform in <filepath>...\hal\src\userhal.cpp</filepath>. </p> <p>See <xref href="GUID-A7ECF51F-F96A-5251-A71F-2F269C8C0664.dita">Writing accessor functions |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
200 |
for derived attributes</xref>. </p></section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
201 |
<section id="GUID-0561268F-C0D0-4E33-85A7-D90F3099E5D1"><title>Accessor functions call UserSvr::HalFunction()</title><p>Typically, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
202 |
an accessor function implementation calls <xref href="GUID-9EF04FB9-B36F-3A6F-AF3F-F2238BD181E9.dita#GUID-9EF04FB9-B36F-3A6F-AF3F-F2238BD181E9/GUID-7F07C14C-E69A-3277-8BFF-0CE2A820166D"><apiname>UserSvr::HalFunction()</apiname></xref>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
203 |
specifying a group number, as defined in <xref href="GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7.dita"><apiname>THalFunctionGroup</apiname></xref>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
204 |
and a function-id that is related to the attribute, but is <i>not</i> the |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
205 |
attribute number as defined in <xref href="GUID-72B0351E-E8D1-3990-9673-A6713F923BC9.dita"><apiname>TAttribute</apiname></xref>. Function numbers |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
206 |
are published in <filepath>u32hal.h</filepath>, and exported into <filepath>...\epoc32\include</filepath>; |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
207 |
for example, the enumerators of the enum <codeph>TDigitiserHalFunction</codeph>. </p> <p>This |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
208 |
means that it is the accessor function, which is part of Symbian platform |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
209 |
generic code, that decides which HAL handler is to deal with a request (as |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
210 |
identified by the attribute). </p> <p>The kernel uses the HAL group number |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
211 |
as an index to dispatch the call to the correct HAL handler. </p> <p>Note |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
212 |
that there may be cases where access to a HAL attribute may be handled through |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
213 |
a device driver or server. </p></section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
214 |
<section id="GUID-14E8EB8B-35FD-4780-8096-249742595207"><title>UserSvr::HalFunction() calls ExecHandler::HalFunction()</title><p>The |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
215 |
static function <codeph>UserSvr::HalFunction()</codeph>, which is <i>internal</i> to |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
216 |
Symbian platform, is the user side point of access. It takes a <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-366CC4B8-C6BD-5DCC-B55D-6D87CD5C8E64">HAL group</xref> to identify a set of related hardware features. In addition, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
217 |
it takes a function-id to identify specific hardware functionality within |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
218 |
the HAL group, for example, one of the <codeph>TDisplayHalFunction</codeph> enumerators. </p> <p>A |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
219 |
call to this function results in a call to the kernel side function <codeph>exechandler::HalFunction()</codeph>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
220 |
passing the group number and the function-id. This, in turn, finds the appropriate <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-1B59A40C-D023-5555-8E5E-DF18D653D321">HAL |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
221 |
handler</xref> function in the internal array <codeph>K::HalFunction[]</codeph>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
222 |
using the group number as the index. </p> <p> <codeph>UserSvr::HalFunction()</codeph> is |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
223 |
exported from <filepath>euser.dll</filepath>, and is therefore accessible |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
224 |
from the user side. However, it is <i>not intended for general third party |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
225 |
use</i>. </p> <p>For information purposes, the <codeph>UserSvr</codeph> class |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
226 |
is defined in the source tree header file <filepath>...\e32\include\e32svr.h</filepath>, |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
227 |
which is exported to <filepath>...\epoc32\include\</filepath>. </p></section> |
307f4279f433
Initial contribution of the Adaptation Documentation.
Graeme Price <GRAEME.PRICE@NOKIA.COM>
parents:
diff
changeset
|
228 |
</conbody></concept> |