xref: /external/parameter-framework/tools/xmlGenerator

# 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]
                             [--target-schemas-dir TARGET_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 `--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.
- 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.

### hostDomainGenerator.sh

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


#### How it works
TODO