Configuration: -Attribute Definition Files

The attributes that can be used on a device are defined in two configuration -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 the -Values 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:

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, i.e. 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.

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

<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

Attributes EMachineUid and EManufacturer 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 ...\hal\inc\hal_data.h.

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.

+ + + + + +Configuration: +Attribute Definition FilesDescribes the format of configuration files +

The attributes that can be used on a device are defined in two configuration +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 the +Values 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:

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, i.e. 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.

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

<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

Attributes EMachineUid and EManufacturer 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 ...\hal\inc\hal_data.h.

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.

\ No newline at end of file