android13/external/parameter-framework/upstream/tools/xmlGenerator/README.md

XML Generator

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.

EDD Syntax

Introduction

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 :

• Easy to write
• Easy to read
• Nearly twice as compact as it's equivalent in XML
• Less merge conflicts and easy solving
• Can be split in multiple files
• Intuitive syntax and comprehension when you know the PFW concepts

But has a couple of drawbacks:

• it is not supported natively by the PFW. It needs to be compiled into XML.
• it supports only tabulation indentation

Concepts

The EDD adds a couple of concepts over the PFW ones in order to extend the concepts used in the Settings files.

DomainGroup

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 :

• Codec.Flow (containing the Unmute and Mute configurations)
• Codec.Configure.IHF (The RoutageState Includes Configure rule will apply to all configurations inside the Codec.Configure.* domains)

ConfigurationGroup

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:

• TTY
• CsvCall.Output.IHF
• CsvCall.Outout.Earpiece

As with domainGroup, the Mode Is InCsvCall rule applies to all CsvCall.Output.* configurations in the ExternalDSP domain.

ConfigurationType

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:

• Modem.Bind (applicable if Mode Is InCsvCall and BandRinging is Modem)
• Modem.Unbind (no rule, i.e. applicable by default)

Component

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 42

Preprocessor

The 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.

Style

Here are a few recommendations to follow when writing Settings using EDD:

Rules

• if you need to modify a rule, do not hesitate to rework it globally.
• keep rule depth under 3-4.
• factorize the rules, taking 3 minute to write a Karnaugh map is worth it.
• comment, comment, comment !

Enum Parameters

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

String Parameters

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

XML Generation

Once a .edd file is ready to be tested, it is possible to generate the corresponding XML file.

domainGenerator.py

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]
                         [--validate] [--verbose]

Explanation:

• The "top-level configuration file" is the same as the one provided by the parameter-framework client to instantiate it. The plugins referenced in that file are not used.
• The "criteria file" lists all criteria and possible values used in the EDD files.
• The initial settings file is an XML file containing a single <ConfigurableDomains> (plural) tag; it may not overlap with the other sources below. It will be imported into the settings.
• Domain files are XML files, each containing a single <ConfigurableDomain> (singular) tag. They all will be imported in the order of the command line into the settings.
• EDD files are all the files in EDD syntax you want to add to your Settings.
• The optional --schemas-dir argument lets you change the directory containing the XML Schemas in the context of the XML generation only (see the --validate option).
• The optional --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.

How it works

TODO