diff options
author | David Wagner <david.wagner@intel.com> | 2014-03-06 14:58:29 +0100 |
---|---|---|
committer | David Wagner <david.wagner@intel.com> | 2014-09-10 12:04:36 +0200 |
commit | f811b7b53c0c2f0d4320c70230e609619c5087c1 (patch) | |
tree | e96266eb13098f5a82aef2d3079b626653706dd2 /tools/xmlGenerator | |
parent | e8088d0f60d895a733c00953c0fdd4e9daf0b279 (diff) | |
download | external_parameter-framework-f811b7b53c0c2f0d4320c70230e609619c5087c1.zip external_parameter-framework-f811b7b53c0c2f0d4320c70230e609619c5087c1.tar.gz external_parameter-framework-f811b7b53c0c2f0d4320c70230e609619c5087c1.tar.bz2 |
More README files
- More details in the root README.md file; add a nice diagram
- Add a lot of README files in subdirectories
Signed-off-by: David Wagner <david.wagner@intel.com>
Diffstat (limited to 'tools/xmlGenerator')
-rw-r--r-- | tools/xmlGenerator/README.md | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/tools/xmlGenerator/README.md b/tools/xmlGenerator/README.md new file mode 100644 index 0000000..2b10ae6 --- /dev/null +++ b/tools/xmlGenerator/README.md @@ -0,0 +1,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 |