|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <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> |
|
13 <p>The attributes that can be used on a device are defined in two |
|
14 configuration files. . </p> |
|
15 <section id="GUID-8648B87A-B712-5458-850A-FDF318669FE3"><title>Config.hcf |
|
16 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 |
|
17 whether attributes: </p> <ul> |
|
18 <li id="GUID-F47EC58A-2E93-5D57-ADD8-F2D7B440F555"><p>are read-only </p> </li> |
|
19 <li id="GUID-F8BEB68C-3D90-5517-80D5-AC7B2EA6FDEC"><p>can be read |
|
20 and written </p> </li> |
|
21 <li id="GUID-9FFE7AE2-32FF-5B30-8458-728A08F5EBC7"><p>are simply stored |
|
22 by the HAL - the non-derived attributes </p> </li> |
|
23 <li id="GUID-BE8EB94D-ED03-5066-A8AE-DC0294A828D9"><p>require calls |
|
24 to other components to obtain or set their values - the derived attributes. </p> </li> |
|
25 </ul> <p>The file must be created in the <filepath>...\Variant\hal\...</filepath> directory. </p> <p>Note that: </p> <ul> |
|
26 <li id="GUID-46D60900-655F-5DEC-AED2-5AC7F3D5C32A"><p> <i>all</i> supported |
|
27 attributes must have an entry in the Config file <filepath>config.hcf</filepath> </p> </li> |
|
28 <li id="GUID-0A474EFD-E146-5D65-AD22-54FE50FA7E68"><p> <i>all</i> non-derived |
|
29 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> |
|
30 </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 |
|
31 file before the C++ compiler is invoked. The generated binary maps |
|
32 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 |
|
33 implementation, any changes to the files will be picked up by the |
|
34 supplied makefile, <filepath>...\hal\config.mke</filepath>. The necessary |
|
35 changes are made to the generated <filepath>config.cpp</filepath> file |
|
36 when the HAL is built. </p> <p>Any additional functions must be added |
|
37 to the implementation file by hand, e.g. in a file called <filepath>imp.cpp</filepath>. However, this would be unusual because all likely |
|
38 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 |
|
39 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 |
|
40 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>. |
|
41 Where more than one property is specified, they are separated by commas. |
|
42 If specified, the initial colon is required. Currently, only the two |
|
43 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 |
|
44 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 |
|
45 for all attributes that appear in the Config file. It indicates that |
|
46 the attribute is meaningful on this platform. Attributes that do not |
|
47 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 |
|
48 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 |
|
49 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 |
|
50 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> |
|
51 <li id="GUID-F9FE0364-512E-5348-B50D-041DD54DD5F3"><p>0, which means |
|
52 that the specified attribute is not derived, but is just a constant |
|
53 stored by the HAL. </p> </li> |
|
54 <li id="GUID-C078572B-3E53-571E-8B2F-04516D3D7C9D"><p>the name of |
|
55 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> |
|
56 </ul> <p><b>Comments</b> </p> <p>The order in which attributes are defined |
|
57 is not important. Comments may be included by starting a line with |
|
58 //. A comment <i>must</i> be on its own line and cannot be appended |
|
59 to an attribute specification. </p> </section> |
|
60 <section id="GUID-3514023A-9CB6-578F-9928-FD0971B81BEF"><title>Values.hda |
|
61 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 |
|
62 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 |
|
63 into a C++ source file before the C++ compiler is invoked. </p> <p>After initial implementation, any changes to the file will be picked |
|
64 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 |
|
65 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 |
|
66 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 |
|
67 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. |
|
68 It may be specified in various ways, but depends on the attribute, |
|
69 and may be one of the following: </p> <ul> |
|
70 <li id="GUID-5C0A1713-DC06-58F1-988C-CD8EB4F774A2"><p>a decimal integer |
|
71 constant </p> </li> |
|
72 <li id="GUID-1D5479D3-AA7D-587E-89CF-F2ACF4E222AE"><p>a hexadecimal |
|
73 integer constant, by prepending <codeph>0x</codeph> </p> </li> |
|
74 <li id="GUID-FD6C4845-8D85-54F3-AB82-D4A92D09CB8D"><p>an enumerated |
|
75 value for those attributes that have a corresponding enumeration in <filepath>...\hal\inc\hal_data.h</filepath>. Note that any substring which |
|
76 is not ambiguous within the enumerated type is acceptable; matching |
|
77 is not case sensitive. For example, <codeph>intel</codeph> would be |
|
78 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> |
|
79 <li id="GUID-912B02EB-A3A7-5EA0-B350-1637D5D62EFD"><p> <codeph>bit1 |
|
80 + bit2 + ... + bitn</codeph>, for those attributes with corresponding |
|
81 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. |
|
82 Any substring which is not ambiguous within the bitmask type is acceptable |
|
83 and matching is not case sensitive. </p> </li> |
|
84 </ul> <p><b>Comments</b> </p> <p>The order in which attributes are defined |
|
85 is not important. Comments may be included by starting a line with |
|
86 //. A comment <i>must</i> be on its own line and cannot be appended |
|
87 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 |
|
88 in the normal way. These values should be placed in the values file |
|
89 and in product specific header files, not in <filepath>...\hal\inc\hal_data.h</filepath></note>.</p> <codeblock xml:space="preserve"> </codeblock> </section> |
|
90 <section id="GUID-A939F6FD-F3AD-4445-BF25-B2DC26369F91"><title>Example |
|
91 of a non-derived attribute</title> <p>A line similar to the following |
|
92 in the <filepath>values.hda</filepath> file defines the machine Uid |
|
93 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 |
|
94 by the HAL. </p> <codeblock id="GUID-2E744820-D5A6-50E1-8449-F8FE69F92796" xml:space="preserve">EMachineUid= 0</codeblock> </section> |
|
95 <section id="GUID-B8778DDA-DDC5-46D5-B668-D8B788AE23C9"><title>Example |
|
96 (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 |
|
97 display contrast. This states that the display contrast is settable, |
|
98 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> |
|
99 <section id="GUID-83AF21A8-517D-442F-B621-1921A2A8C40E"><title>Example |
|
100 (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 |
|
101 display size. </p> <codeblock id="GUID-ACD86D8C-887C-5B32-813A-6E468DE46E74" xml:space="preserve">EDisplayXPixels=ProcessDisplayCurrentModeInfo |
|
102 EDisplayYPixels=ProcessDisplayCurrentModeInfo</codeblock> <p>This |
|
103 is read only information, so the entries do not contain the "set" |
|
104 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> |
|
105 </conbody></concept> |