<?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-52583CC7-483E-54B5-8094-F0F61BD46B7F" xml:lang="en"><title>Configuration: Attribute Definition Files</title><shortdesc>Describes the format of configuration files.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The attributes that can be used on a device are defined in two

configuration files. . </p>

<section id="GUID-8648B87A-B712-5458-850A-FDF318669FE3"><title>Config.hcf

file</title> <p>The purpose of this file, <filepath>config.hcf</filepath>, is to define the <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-174A663C-3943-5D36-B507-D97A687C168C">attributes</xref> that have meaning on this hardware. It specifies

whether attributes: </p> <ul>

<li id="GUID-F47EC58A-2E93-5D57-ADD8-F2D7B440F555"><p>are read-only </p> </li>

<li id="GUID-F8BEB68C-3D90-5517-80D5-AC7B2EA6FDEC"><p>can be read

and written </p> </li>

<li id="GUID-9FFE7AE2-32FF-5B30-8458-728A08F5EBC7"><p>are simply stored

by the HAL - the non-derived attributes </p> </li>

<li id="GUID-BE8EB94D-ED03-5066-A8AE-DC0294A828D9"><p>require calls

to other components to obtain or set their values - the derived attributes. </p> </li>

</ul> <p>The file must be created in the <filepath>...\Variant\hal\...</filepath> directory. </p> <p>Note that: </p> <ul>

<li id="GUID-46D60900-655F-5DEC-AED2-5AC7F3D5C32A"><p> <i>all</i> supported

attributes must have an entry in the Config file <filepath>config.hcf</filepath>  </p> </li>

<li id="GUID-0A474EFD-E146-5D65-AD22-54FE50FA7E68"><p> <i>all</i> non-derived

attributes also need an entry in the<xref href="GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita#GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F/GUID-3514023A-9CB6-578F-9928-FD0971B81BEF">Values file</xref> <filepath>values.hda</filepath>. </p> </li>

</ul> <p>The build system uses the Perl script <filepath>halcfg.pl</filepath> to convert text information in the Config file into a C++ source

file before the C++ compiler is invoked. The generated binary maps

to the data members defined in the <codeph>HalInternal</codeph> class. <i>Note that this class is internal to Symbian</i>. </p> <p>After initial

implementation, any changes to the files will be picked up by the

supplied makefile, <filepath>...\hal\config.mke</filepath>. The necessary

changes are made to the generated <filepath>config.cpp</filepath> file

when the HAL is built. </p> <p>Any additional functions must be added

to the implementation file by hand, e.g. in a file called <filepath>imp.cpp</filepath>. However, this would be unusual because all likely

functions are already implemented in <filepath>...\hal\src\userhal.cpp</filepath>. </p> <p>The config file consists of a number of lines of text in

the form: </p> <codeblock id="GUID-837B7F2C-E2CB-5DB6-97D5-AA009C335DA7" xml:space="preserve">&lt;attrib&gt; [:&lt;prop1&gt;, &lt;prop2&gt;, ...] = &lt;implementation&gt;</codeblock> <p>where the pair of square brackets indicates optional items. </p> <p><b>&lt;attrib&gt;</b> </p> <p>This is one of the values of the enumeration <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> in the source file <filepath>...\hal\inc\hal_data.h</filepath>  </p> <p><b>&lt;prop1&gt;, &lt;prop2&gt;,...</b> </p> <p>These are optional property

specifications defined by the enumeration <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-F1E5A60F-FB3C-387A-9055-BC5478ADB815"><apiname>HALData::TAttributeProperty</apiname></xref> in the source file <filepath>...\hal\inc\hal_data.h</filepath>.

Where more than one property is specified, they are separated by commas.

If specified, the initial colon is required. Currently, only the two

properties <xref href="GUID-59379CFA-F4FD-36B0-855F-A9528B3458B4.dita"><apiname>EValid</apiname></xref> and <xref href="GUID-490A3E37-17DB-3702-9E8C-FD3F555A3080.dita"><apiname>ESettable</apiname></xref> are defined. Note that any substring which is not ambiguous within

the enumerated type is acceptable; matching is not case sensitive. </p> <p>The property <xref href="GUID-59379CFA-F4FD-36B0-855F-A9528B3458B4.dita"><apiname>EValid</apiname></xref> is defined implicitly

for all attributes that appear in the Config file. It indicates that

the attribute is meaningful on this platform. Attributes that do not

appear in the Config file do not have this property, and 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> or <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> which refer

to those attributes return <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. </p> <p>The property <xref href="GUID-490A3E37-17DB-3702-9E8C-FD3F555A3080.dita"><apiname>ESettable</apiname></xref>, means that an attribute

is modifiable. Calls to <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> for attributes

without this property return <xref href="GUID-F89DA3F0-2A48-3F9B-8F08-29350E92D0E4.dita"><apiname>KErrNotSupported</apiname></xref>. </p> <p><b>&lt;implementation&gt;</b> </p> <p>Defines whether 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 derived. It can be: </p> <ul>

<li id="GUID-F9FE0364-512E-5348-B50D-041DD54DD5F3"><p>0, which means

that the specified attribute is not derived, but is just a constant

stored by the HAL. </p> </li>

<li id="GUID-C078572B-3E53-571E-8B2F-04516D3D7C9D"><p>the name of

a function used to implement <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> for that specified attribute. </p> </li>

</ul> <p><b>Comments</b> </p> <p>The order in which attributes are defined

is not important. Comments may be included by starting a line with

//. A comment <i>must</i> be on its own line and cannot be appended

to an attribute specification. </p> </section>

<section id="GUID-3514023A-9CB6-578F-9928-FD0971B81BEF"><title>Values.hda

file</title> <p>The purpose of this file, <filepath>values.hda</filepath>, is to specify the initial values of the non-derived <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-174A663C-3943-5D36-B507-D97A687C168C">attributes</xref>, those attributes which are simply stored in, and

retrieved from, the HAL. It must be created in the <filepath>...\variant\hal\...</filepath> directory. </p> <p>The build system uses the Perl script <filepath>halcfg.pl</filepath> to convert text information in the Values file

into a C++ source file before the C++ compiler is invoked. </p> <p>After initial implementation, any changes to the file will be picked

up by the supplied makefile, <filepath>...\hal\config.mke</filepath>. The necessary changes are made to the generated <filepath>values.cpp</filepath> file when the HAL is built. </p> <p>Any additional functions must

be added to the implementation file by hand, e.g. in a file called <filepath>imp.cpp</filepath>. However, this would be unusual because all likely

functions are already implemented in <filepath>...\hal\src\userhal.cpp</filepath>. </p> <p>The values file consists of a number of lines of text in

the form: </p> <codeblock id="GUID-2BD2A5EA-376A-5B7A-BF2F-7DDFEC9F39EC" xml:space="preserve">&lt;attrib&gt; = &lt;value&gt;</codeblock> <p><b>&lt;attrib&gt;</b> </p> <p>This is one of the values of the enumeration <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 the header file <filepath>...\hal\inc\hal_data.h</filepath>. </p> <p><b>&lt;value&gt;</b> </p> <p>This is the initial value of the attribute.

It may be specified in various ways, but depends on the attribute,

and may be one of the following: </p> <ul>

<li id="GUID-5C0A1713-DC06-58F1-988C-CD8EB4F774A2"><p>a decimal integer

constant </p> </li>

<li id="GUID-1D5479D3-AA7D-587E-89CF-F2ACF4E222AE"><p>a hexadecimal

integer constant, by prepending <codeph>0x</codeph>  </p> </li>

<li id="GUID-FD6C4845-8D85-54F3-AB82-D4A92D09CB8D"><p>an enumerated

value for those attributes that have a corresponding enumeration in <filepath>...\hal\inc\hal_data.h</filepath>. Note that any substring which

is not ambiguous within the enumerated type is acceptable; matching

is not case sensitive. For example, <codeph>intel</codeph> would be

an acceptable abbreviation for <codeph>EManufacturer_Intel</codeph> in the enumeration <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-FF91E5FE-CD00-3D2F-AE88-F601611F9A55"><apiname>HALData::TManufacturer</apiname></xref>. </p> </li>

<li id="GUID-912B02EB-A3A7-5EA0-B350-1637D5D62EFD"><p> <codeph>bit1

+ bit2 + ... + bitn</codeph>, for those attributes with corresponding

bitmask enumerations in <filepath>...\hal\inc\hal_data.h</filepath>, and declared with the <codeph>bitmask</codeph> pseudo-keyword. <codeph>bit1</codeph>, <codeph>bit2</codeph> etc. are values of the enumeration.

Any substring which is not ambiguous within the bitmask type is acceptable

and matching is not case sensitive. </p> </li>

</ul> <p><b>Comments</b> </p> <p>The order in which attributes are defined

is not important. Comments may be included by starting a line with

//. A comment <i>must</i> be on its own line and cannot be appended

to an attribute specification. </p><p><note> Attributes <xref href="GUID-81DC05E0-DEF1-3A67-B0D5-C5B65FC42E9C.dita"><apiname>EMachineUid</apiname></xref> and <xref href="GUID-641E454C-59AD-39C4-8BC6-A9A86042A77B.dita"><apiname>EManufacturer</apiname></xref> should be allocated UID values

in the normal way. These values should be placed in the values file

and in product specific header files, not in <filepath>...\hal\inc\hal_data.h</filepath></note>.</p> <codeblock xml:space="preserve"> </codeblock> </section>

<section id="GUID-A939F6FD-F3AD-4445-BF25-B2DC26369F91"><title>Example

of a non-derived attribute</title> <p>A line similar to the following

in the <filepath>values.hda</filepath> file defines the machine Uid

to the HAL, and shows how a value is paired to an attribute. </p> <codeblock id="GUID-15C4C6A7-10F2-5782-96CE-3A66C074683E" xml:space="preserve">EMachineUid= 0x1000a682</codeblock> <p>A line similar to the following in the <filepath>config.hcf</filepath> file indicates that the value is not derived but is simply stored

by the HAL. </p> <codeblock id="GUID-2E744820-D5A6-50E1-8449-F8FE69F92796" xml:space="preserve">EMachineUid= 0</codeblock> </section>

<section id="GUID-B8778DDA-DDC5-46D5-B668-D8B788AE23C9"><title>Example

(1) of a derived attribute</title> <p>The following line in the <filepath>config.hcf</filepath> file shows how to configure the API for the

display contrast. This states that the display contrast is settable,

and that the function to do this is called <codeph>ProcessDisplayContrast</codeph>. </p> <codeblock id="GUID-BC43C02A-4436-5BFF-AA35-BF3D2F33AE3C" xml:space="preserve">EDisplayContrast : set = ProcessDisplayContrast</codeblock> </section>

<section id="GUID-83AF21A8-517D-442F-B621-1921A2A8C40E"><title>Example

(2) of a derived attribute</title> <p>The following lines in the <filepath>config.hcf</filepath> file shows how to configure the API for the

display size. </p> <codeblock id="GUID-ACD86D8C-887C-5B32-813A-6E468DE46E74" xml:space="preserve">EDisplayXPixels=ProcessDisplayCurrentModeInfo

EDisplayYPixels=ProcessDisplayCurrentModeInfo</codeblock> <p>This

is read only information, so the entries do not contain the "set"

keyword. The values are derived via the API function <codeph>ProcessDisplayCurrentModeInfo</codeph>, and there is no corresponding entry in <filepath>values.hda</filepath>. </p> </section>

</conbody></concept>