This set of tools is used to transform files written in the pseudo language (referred to as "Extended Domain Description") into XML parameter-framework Settings files. The extension of such files are usually .edd
or .pfw
.
The Extended Domain Description (EDD) has been designed to help describing multiple and complex PFW settings. It is a recursive structured language with tabulation indentation (inspired from python).
It has several advantages :
But has a couple of drawbacks:
The EDD adds a couple of concepts over the PFW ones in order to extend the concepts used in the Settings files.
A domain group can contain other domain groups and domains. Those inner domains will be prefixed with the name of the domain group.
The tag for domain groups is domainGroup
.
Example
domainGroup: Codec domain: Flow conf: Unmute /Audio/codec/playback/master_mute = 0 conf: Mute /Audio/codec/playback/master_mute = 1 domainGroup: Configure RoutageState Includes Configure domain: IHF [...]
will create the domains :
RoutageState Includes Configure
rule will apply to all configurations inside the Codec.Configure.*
domains)A configuration group can contain other configuration groups and configurations. Those inner configurations will be prefixed with the name of the configuration group.
The tag for configuration groups is confGroup
.
Example
domain: ExternalDSP conf: TTY [...] confGroup: CsvCall Mode Is InCsvCall confGroup: Output conf: IHF [...] conf: Earpiece [...]
will create the following configurations in the ExternalDSP
domain:
As with domainGroup, the Mode Is InCsvCall
rule applies to all CsvCall.Output.*
configurations in the ExternalDSP
domain.
A configuration type is the specialization concept. When defining a configuration type, any configuration in the containing domain (or domain group) with the same name will inherit the configuration type rule.
The tag for configuration types is confType
.
Example
domain: ExternalDSP confType: Bind Mode Is InCsvCall confGroup: Modem conf: Bind BandRinging is Modem [...] conf: Unbind [...]
will create the following configurations in the ExternalDSP
domain:
Mode Is InCsvCall
and BandRinging is Modem
)A component can be used to factorize parameter names in configurations.
The tag for components is component
.
domain: Foo conf: Bar component: /System/some_element parameter1 = "egg" parameter2 = "spam" /System/another_element/parameter3 = 42
will create a domain Foo containing a configuration Bar (no rule, i.e. applicable by default) that will set these 3 parameters:
/System/some_element/parameter1
to "egg"/System/some_element/parameter2
to "spam"/System/another_element/parameter3
to 42The xmlGenerator uses m4 to preprocess the files before parsing them. You may use any macro implemented by m4, such as define
and include
. This is deprecated and we do not recommend using it.
Here are a few recommendations to follow when writing Settings using EDD:
When setting an enum parameter value, use its lexical space, not its numerical space. E.g. don't write
/Subsystem/frequency = 5
Write instead:
/Subsystem/frequency = f48kHz
In an EDD file, string parameters may not contain newlines. Apart from that, all characters are supported. Also, leading spaces are ignored. Do not surround a string parameter's value with quotes. Don't write:
/Subsystem/string_parameter = "some string value"
Write instead:
/Subsystem/string_parameter = some string value
Once a .edd
file is ready to be tested, it is possible to generate the corresponding XML file.
This python tool is self-documented: you may run domainGenerator.py -h
to get its full usage.
It prints the resulting XML on the standard output. Its syntax is:
domainGenerator.py [-h] --toplevel-config TOPLEVEL_CONFIG_FILE --criteria CRITERIA_FILE [--initial-settings XML_SETTINGS_FILE] [--add-domains XML_DOMAIN_FILE [XML_DOMAIN_FILE ...]] [--add-edds EDD_FILE [EDD_FILE ...]] [--schemas-dir SCHEMAS_DIR] [--target-schemas-dir TARGET_SCHEMAS_DIR] [--validate] [--verbose]
Explanation:
<ConfigurableDomains>
(plural) tag; it may not overlap with the other sources below. It will be imported into the settings.<ConfigurableDomain>
(singular) tag. They all will be imported in the order of the command line into the settings.--schemas-dir
argument lets you change the directory containing the XML Schemas in the context of the XML generation only (see the --validate
option).--target-schemas-dir
argument lets you change the directory containing the XML Schemas on the target device (the one the parameter-framework will run on) if it is using Schema validation and if different than the default.--validate
option check the validity of all XML files involved in the process.Regarding XML Domain files and EDD files:
In theory, the order doesn't matter but since files are parsed in the order of the command line, you'll get different (although equivalent) files if you change the order, which makes it more difficult to compare versions.
The "criteria file" must look something like this:
ExclusiveCriterion Criterion1Name : Criterion1Value1 Criterion1Value2 InclusiveCriterion Criterion2Name : Criterion2Value1 Criterion2Value2
I.e. One criterion by line, starting by its kind, then its name, followed by a semicolon and then all possible values separated by spaces.
This script is now deprecated and replaced by domainGenerator.py (see above).
It prints the resulting XML on the standard output. Its syntax is:
hostDomainGenerator.sh [--validate] <top-level configuration file> <criteria file> <EDD files...>
See domainGenerator.py above for the explanation of the arguments.
TODO