Configuration: Attribute Definition Files

Config.hcf file

The purpose of this file, config.hcf, is to define the attributes that have meaning on this hardware. It specifies whether attributes:

• are read-only

• can be read and written

• are simply stored by the HAL - the non-derived attributes

• require calls to other components to obtain or set their values - the derived attributes.

The file must be created in the ...\Variant\hal\... directory.

Note that:

• all supported attributes must have an entry in the Config file config.hcf

• all non-derived attributes also need an entry in theValues file values.hda.

The build system uses the Perl script halcfg.pl 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 HalInternal class. Note that this class is internal to Symbian.

After initial implementation, any changes to the files will be picked up by the supplied makefile, ...\hal\config.mke. The necessary changes are made to the generated config.cpp file when the HAL is built.

Any additional functions must be added to the implementation file by hand, e.g. in a file called imp.cpp. However, this would be unusual because all likely functions are already implemented in ...\hal\src\userhal.cpp.

The config file consists of a number of lines of text in the form:

<attrib> [:<prop1>, <prop2>, ...] = <implementation>

where the pair of square brackets indicates optional items.

<attrib>

This is one of the values of the enumeration HALData::TAttribute in the source file ...\hal\inc\hal_data.h

<prop1>, <prop2>,...

These are optional property specifications defined by the enumeration HALData::TAttributeProperty in the source file ...\hal\inc\hal_data.h. Where more than one property is specified, they are separated by commas. If specified, the initial colon is required. Currently, only the two properties EValid and ESettable are defined. Note that any substring which is not ambiguous within the enumerated type is acceptable; matching is not case sensitive.

The property EValid 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 HAL::Get() or HAL::Set() which refer to those attributes return KErrNotSupported.

The property ESettable, means that an attribute is modifiable. Calls to HAL::Set() for attributes without this property return KErrNotSupported.

<implementation>

Defines whether an attribute is derived. It can be:

• 0, which means that the specified attribute is not derived, but is just a constant stored by the HAL.

• the name of a function used to implement HAL::Get() and HAL::Set() for that specified attribute.

Comments

The order in which attributes are defined is not important. Comments may be included by starting a line with //. A comment must be on its own line and cannot be appended to an attribute specification.

Values.hda file

The purpose of this file, values.hda, is to specify the initial values of the non-derived attributes, those attributes which are simply stored in, and retrieved from, the HAL. It must be created in the ...\variant\hal\... directory.

The build system uses the Perl script halcfg.pl to convert text information in the Values file into a C++ source file before the C++ compiler is invoked.

After initial implementation, any changes to the file will be picked up by the supplied makefile, ...\hal\config.mke. The necessary changes are made to the generated values.cpp file when the HAL is built.

Any additional functions must be added to the implementation file by hand, e.g. in a file called imp.cpp. However, this would be unusual because all likely functions are already implemented in ...\hal\src\userhal.cpp.

The values file consists of a number of lines of text in the form:

<attrib> = <value>

<attrib>

This is one of the values of the enumeration HALData::TAttribute defined in the header file ...\hal\inc\hal_data.h.

<value>

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:

• a decimal integer constant

• a hexadecimal integer constant, by prepending 0x

• an enumerated value for those attributes that have a corresponding enumeration in ...\hal\inc\hal_data.h. Note that any substring which is not ambiguous within the enumerated type is acceptable; matching is not case sensitive. For example, intel would be an acceptable abbreviation for EManufacturer_Intel in the enumeration HALData::TManufacturer.

• bit1 + bit2 + ... + bitn, for those attributes with corresponding bitmask enumerations in ...\hal\inc\hal_data.h, and declared with the bitmask pseudo-keyword. bit1, bit2 etc. are values of the enumeration. Any substring which is not ambiguous within the bitmask type is acceptable and matching is not case sensitive.

Comments

The order in which attributes are defined is not important. Comments may be included by starting a line with //. A comment must be on its own line and cannot be appended to an attribute specification.

Example of a non-derived attribute

A line similar to the following in the values.hda file defines the machine Uid to the HAL, and shows how a value is paired to an attribute.

EMachineUid= 0x1000a682

A line similar to the following in the config.hcf file indicates that the value is not derived but is simply stored by the HAL.

EMachineUid= 0

Example (1) of a derived attribute

The following line in the config.hcf 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 ProcessDisplayContrast.

EDisplayContrast : set = ProcessDisplayContrast

Example (2) of a derived attribute

The following lines in the config.hcf file shows how to configure the API for the display size.

EDisplayXPixels=ProcessDisplayCurrentModeInfo
EDisplayYPixels=ProcessDisplayCurrentModeInfo

This is read only information, so the entries do not contain the "set" keyword. The values are derived via the API function ProcessDisplayCurrentModeInfo, and there is no corresponding entry in values.hda.