--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-52583CC7-483E-54B5-8094-F0F61BD46B7F.dita Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,122 @@
+<?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"><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>, 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"><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