--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Adaptation/GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita Fri Oct 15 14:32:18 2010 +0100
@@ -0,0 +1,105 @@
+<?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"><attrib> [:<prop1>, <prop2>, ...] = <implementation></codeblock> <p>where the pair of square brackets indicates optional items. </p> <p><b><attrib></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><prop1>, <prop2>,...</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><implementation></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"><attrib> = <value></codeblock> <p><b><attrib></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><value></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>
\ No newline at end of file