1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
# 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.
### hostDomainGenerator.sh
It prints the resulting XML on the standard output. Its syntax is:
hostDomainGenerator.sh [--validate] <top-level configuration file> <criteria file> <EDD files...>
Explanation:
- The optional `--validate` option check the validity of all XML files involved
in the process.
- 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.
- EDD files are all the files you want to use to generate you Settings. In
theory, the order doesn't matter but since the 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
|
