<?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-9AE254D4-AA60-579E-8D9D-F2797106A413" xml:lang="en"><title>User-Side

Hardware Abstraction Technology</title><shortdesc>Description of HAL types and interfaces.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The User-Side Hardware Abstraction (HAL) component provides a platform-independent

way to access and control many device specific features, and to hide hardware-specific

functionality. For example, HAL can be used to find out if a screen backlight

is present or not, or to set the display contrast. This topic </p>

<section id="GUID-174A663C-3943-5D36-B507-D97A687C168C"><title>Attributes</title> <p>Specific

items of hardware related information are referred to as <i>attributes</i>.

Symbian platform defines two types of attribute: </p> <ul>

<li id="GUID-3A220CC5-7D56-5FB8-A69A-EFAAC0159561"><p>Non-derived attribute.

This is an attribute where the information it represent is simply a value

that is stored in, and retrieved from, the HAL. </p> </li>

<li id="GUID-934EFFE7-4768-5919-8900-6DE6915E3195"><p>Derived attribute. This

is an attribute that requires a software call to obtain and set its value.

The software component is, ultimately provided by a driver, kernel extension

or by the kernel itself. The drivers or kernel extensions normally need porting. </p> </li>

</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

in <filepath>...\hal\inc\hal_data.h</filepath> and is exported to <filepath>...\epoc32\include\</filepath>. </p> <p>To

maintain backwards compatibility, the numbers identifying HAL attributes are

allocated strictly increasing consecutive values, and that a given HAL attribute

always has the same enumeration number on all implementations of Symbian platform.

This means that new HAL attributes can only be added by Symbian. This also

means that the addition of custom HAL attributes is not possible. </p> </section>

<section id="GUID-F1F21DDA-DEA0-502E-83DB-84DDCFA5CBF8"><title>User-side interface</title> <p>Symbian

platform provides the following static functions to get and set information

about specific hardware features: </p> <ul>

<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>

<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>

<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>

</ul> <p>The <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita"><apiname>HAL</apiname></xref> class is defined in the source tree header

file <filepath>...\hal\inc\hal.h</filepath>, and is exported to <filepath>...\epoc32\include\</filepath>.

The functions are exported from the HAL DLL, which is built as part of the

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

identify specific hardware functionality. </p> <p> <codeph>GetAll()</codeph>,

as its name implies gets all available hardware information, but is rarely

used. See <xref href="GUID-124AC7EE-E227-5358-A755-628FFE257250.dita#GUID-124AC7EE-E227-5358-A755-628FFE257250/GUID-D75D3A65-590D-5716-84A7-0195DFCD1656">Dealing

with the HAL::GetAll() function</xref> for more information. </p> <p> <codeph>Get()</codeph> and <codeph>Set()</codeph> each

have a variation that allows a device number to be specified. The device number

allows more than one set of attributes to be used. Each set is associated

with a different device number. This is motivated by the need to support multiple

display screens where each screen is identified as a separate device of the

same 'type'. The idea of a device can be extended other hardware, and indeed

the underlying implementation assumes a device number. If a device number

is not specified and has no meaning, then a default device number of 0 is

assumed for compatibility with the underlying implementation. </p> <p>For

example, on return from code such as: </p> <codeblock id="GUID-D512D36F-C94A-50C2-9245-569C6386E559" xml:space="preserve">...

TInt xpixels;

HAL::Get(EDisplayXPixels, xpixels);

...</codeblock> <p> <codeph> xpixels</codeph> contains the horizontal size

of the display screen in terms of the number of pixels. If you have more than

one screen, i.e. more than one device, then you would use the API variant

that takes a device number. </p> </section>

<section id="GUID-79BE4534-B9C6-5D64-8CB0-E3EEDE8AD293"><title>HAL handler

interface</title> <p>A request for fetching and setting information about

hardware is dealt with by an entity called a HAL handler on the kernel side.

This section describes the types and concepts used to implement a HAL handler. </p> </section>

<section id="GUID-FBA183CB-E9D5-4E70-B65F-A496853D614B"><title>HAL groups and function-ids</title><p>It is useful to group

together requests for information about related hardware features so that

they can be dealt with by a single HAL handler. As an example, all the HAL

screen attributes are in the display group and are handled by the screen (i.e.

video or LCD) driver. This means that a HAL group has a one-to-one association

with a HAL handler. </p> <p>A HAL group has an associated set of function-ids,

which identify requests for different pieces of information to the HAL handler. </p> <p>Symbian

platform identifies HAL groups by a number defined by the <xref href="GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7.dita"><apiname>THalFunctionGroup</apiname></xref> enum

in <filepath>u32hal.h</filepath>, which is exported to <filepath>...\epoc32\include</filepath>.

For example, the <xref href="GUID-7F299BFC-D8A5-3A5A-B8DA-39BF42C99DC6.dita"><apiname>EHalGroupDisplay</apiname></xref> enum value identifies

the group associated with the HAL screen attributes. </p> <p>The function-ids

associated with each HAL group are also defined in <filepath>u32hal.h</filepath>.

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

the function-ids associated with the HAL group <xref href="GUID-7F299BFC-D8A5-3A5A-B8DA-39BF42C99DC6.dita"><apiname>EHalGroupDisplay</apiname></xref>. </p> <p>The

idea of the HAL group is what allows HAL handling functionality to be implemented

in the Variant, rather than in the kernel. </p> <p>Up to 32 groups can be

defined. Often, a HAL group is concerned with mode settings for a particular

piece of hardware; for example there are standard HAL groups for keyboard,

digitiser and display. However, some groups are concerned with some overall

aspect of the platform which extends across all devices; for example, there

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

to a HAL group/function-id pair, although the mapping is not necessarily a

one-to-one relationship. For example, the calls: </p> <codeblock id="GUID-FB9CB26C-3DEF-5E8B-A564-40ECC68AD2FD" xml:space="preserve">TInt xPixels, yPixels;

...

HAL::Get(HALData::EDisplayXPixels,xPixels);

HAL::Get(HALData::EDisplayYPixels,yPixels);

...</codeblock> <p>both result in calls to the screen (i.e. video or LCD)

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>,

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,

there are HAL group/function-id pairs for which there are no corresponding

generic attributes. In these cases, the hardware attributes represented by

the HAL group/function-id pair are used internally, and can only be accessed

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

following picture shows the general idea: </p> <fig id="GUID-95743ED4-8CEC-5BAD-A5C2-9FD16D0485FA">

<image href="GUID-F50E1C81-E80F-5692-996B-3AC2BE995425_d0e422932_href.png" placement="inline"/>

</fig> <p>**Technically, the user side function <codeph>UserSvr::HalFunction()</codeph> will

achieve the same thing, but this is <i>internal to Symbian</i> and is <i>not

intended for general use</i>. </p></section>

<section id="GUID-F28BA77B-D7AA-4D27-8ADF-029F42F800E4"><title>HAL handler implementation</title><p>Most HAL handlers are

implemented as part of a driver, a kernel extension, the Variant or the kernel

itself. Some will need porting. See <xref href="GUID-857F981E-711B-5CA8-AB37-5C700A6140FA.dita">Groups

and the location of their HAL handlers</xref>. </p> <p>An extension or a device

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>,

specifying the group number. It is important to note that it is the extension

or driver's responsibility to do this; in other words, the kernel cannot know

what entity within a final ported Symbian platform is going to be the HAL

handler until it is explicitly told by registration. One point to note is

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

itself. </p> <p>Internally, pointers to the HAL handler are stored in the

array <codeph>K::HalFunction[]</codeph>, and this is indexed by the group

number. </p> <p>On the template board, for example, the HAL handler for the

display group is part of the screen driver. The screen driver source can be

found in <filepath>...\template_variant\specific\lcd.cpp</filepath>. The HAL

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)

    {

    DLcdPowerHandler* pH=(DLcdPowerHandler*)aPtr;

    return pH->HalFunction(aFunction,a1,a2);

    }</codeblock> <p>The following code, implemented in the Create() function

of the main class, does the registration. </p> <codeblock id="GUID-2B8BFFC5-8FC5-5220-BE9D-F02003C41275" xml:space="preserve">TInt DLcdPowerHandler::Create()

    {

    ...

    // install the HAL function

    r=Kern::AddHalEntry(EHalGroupDisplay,halFunction,this);

    if (r!=KErrNone)

        return r;

    ...

    }</codeblock> <p>Security is the responsibility of the HAL handler. If

necessary, it needs to check the capability of the caller's process. Each

information item, as identified by the function-id, can have an associated

capability. </p> <p>Each function-id defined in <filepath>u32hal.h</filepath> is

documented with the required capability. If no capability is listed, then

no specific capability is required. </p> <p>See <xref href="GUID-124AC7EE-E227-5358-A755-628FFE257250.dita">Implementing

HAL handlers</xref> for details. </p> </section>

<section id="GUID-042A8840-2260-5951-8951-E6E2A83F378E"><title>Kernel-side

interface</title> <p>Code such as device drivers that runs on the kernel side

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

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

the group number and function-ids to identify hardware related information.

This means that kernel side code does not use attributes to identify hardware

related information. The implication here is that you <i>may</i> have to make

changes to your kernel side code when porting to another platform. In practice,

no changes may be needed, but at the very least you need to check. </p> </section>

<section id="GUID-43324161-56E6-40A7-A4C4-D3D8435D3568"><title>Config and Values files define attributes</title><p>Although

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

generic, some attributes may not have meaning on some platforms. In addition,

each platform needs to define whether an attribute is either: </p> <ul>

<li id="GUID-5D6B46DF-FAE7-5097-832D-F8FD33A3DB53"><p> <i>non-derived</i>,

i.e. has a value that is simply stored in the HAL, </p> </li>

</ul> <p>or: </p> <ul>

<li id="GUID-B40D5AE3-13E7-50B0-8926-5B3461496DD2"><p> <i>derived</i>, i.e.

requires a call to a software entity to get and set the value. </p> </li>

</ul> <p>This is the role of the <i>Config file</i>. </p> <p>The Config file

contains a list of all the attributes that have meaning on a platform, and

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

identify them. Using a simple syntax, an attribute can be defined as being

derived by associating the attribute symbol with the name of a function. This

function is known as the <i>accessor function</i>. </p> <p>There is also a

file known as the <i>Values file</i> that defines the initial values for all

of the non-derived attributes, i.e. those attributes that are simply stored

in, and retrieved from, the HAL. </p> <p>The Config and Values files are text

files that, for a specific implementation of the HAL, reside in the <filepath>...\variant\hal</filepath> directory.

The MMP file also resides there, and the HAL is built as part of the Variant.

As part of the build process, the Config and Values files are passed to a

Perl script, <filepath>halcfg.pl</filepath>, which translates the contents

into C++ source files. The resulting binaries are linked in as part of the

resulting HAL DLL. </p> <p>In effect, these C++ source files implement the

static data arrays defined by the <codeph>HalInternal</codeph> class. As its

name suggests, <b>this class is internal to Symbian platform</b>, and is only

discussed here to help with understanding. </p> <codeblock id="GUID-35660653-5519-59B9-A8D1-1BC18EA5E46D" xml:space="preserve">class HalInternal

    {

    ...

    static const TUint8 Properties[HAL::ENumHalAttributes];

       ...

    static const TInt InitialValue[HAL::ENumHalAttributes];

    static const THalImplementation Implementation[HAL::ENumHalAttributes];

    ...

    }</codeblock> <p>The data member <codeph>Implementation[]</codeph> is

an array of pointers to the accessor functions </p> <p>See <xref href="GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita">Creating

the Config &amp; Values files</xref> for detailed syntax. </p></section>

<section id="GUID-35FF9B50-7503-4F8E-B7A7-91287FDB57AB"><title>Derived attributes require accessor functions</title><p>Each

derived attribute has a corresponding accessor function. For example, <codeph>ProcessDisplayContrast()</codeph>. </p> <p>All

accessor functions are implemented in <filepath>...\hal\src\userhal.cpp</filepath>,

and are provided by Symbian platform because of the 'connection' to attributes

which are themselves defined as part of the generic platform. </p> <p>Generally

there is one accessor function per derived attribute, although there is nothing

to prevent an accessor function dealing with more than one attribute. The

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

to the correct accessor function. Internally, Symbian platform routes calls

to Get() and Set() for an attribute to the same accessor function, distinguishing

between the two by a boolean value. </p> <p>A new implementation of an accessor

function should rarely, if ever, be needed as all likely accessor functions

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

for derived attributes</xref>. </p></section>

<section id="GUID-0561268F-C0D0-4E33-85A7-D90F3099E5D1"><title>Accessor functions call UserSvr::HalFunction()</title><p>Typically,

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>,

specifying a group number, as defined in <xref href="GUID-66A851A0-2A0C-3624-AEC1-22F6629FABF7.dita"><apiname>THalFunctionGroup</apiname></xref>,

and a function-id that is related to the attribute, but is <i>not</i> the

attribute number as defined in <xref href="GUID-72B0351E-E8D1-3990-9673-A6713F923BC9.dita"><apiname>TAttribute</apiname></xref>. Function numbers

are published in <filepath>u32hal.h</filepath>, and exported into <filepath>...\epoc32\include</filepath>;

for example, the enumerators of the enum <codeph>TDigitiserHalFunction</codeph>. </p> <p>This

means that it is the accessor function, which is part of Symbian platform

generic code, that decides which HAL handler is to deal with a request (as

identified by the attribute). </p> <p>The kernel uses the HAL group number

as an index to dispatch the call to the correct HAL handler. </p> <p>Note

that there may be cases where access to a HAL attribute may be handled through

a device driver or server. </p></section>

<section id="GUID-14E8EB8B-35FD-4780-8096-249742595207"><title>UserSvr::HalFunction() calls ExecHandler::HalFunction()</title><p>The

static function <codeph>UserSvr::HalFunction()</codeph>, which is <i>internal</i> to

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,

it takes a function-id to identify specific hardware functionality within

the HAL group, for example, one of the <codeph>TDisplayHalFunction</codeph> enumerators. </p> <p>A

call to this function results in a call to the kernel side function <codeph>exechandler::HalFunction()</codeph>,

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

handler</xref> function in the internal array <codeph>K::HalFunction[]</codeph>,

using the group number as the index. </p> <p> <codeph>UserSvr::HalFunction()</codeph> is

exported from <filepath>euser.dll</filepath>, and is therefore accessible

from the user side. However, it is <i>not intended for general third party

use</i>. </p> <p>For information purposes, the <codeph>UserSvr</codeph> class

is defined in the source tree header file <filepath>...\e32\include\e32svr.h</filepath>,

which is exported to <filepath>...\epoc32\include\</filepath>. </p></section>

</conbody></concept>