<?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 <xref href="GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita#GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F/GUID-3514023A-9CB6-578F-9928-FD0971B81BEF">the
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>, i.e. 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>