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>
diff --git a/tools/coverage/README.md b/tools/coverage/README.md
new file mode 100644
index 0000000..a825a08
--- /dev/null
+++ b/tools/coverage/README.md
@@ -0,0 +1,61 @@
+# Domain coverage report
+
+## Introduction
+
+During the PFW's life cycle, criteria states are changed and configurations are
+applied.
+
+This report gives the coverage for :
+
+- Criterion: detect easily which criterion state aren't used.
+- Configuration: detect configuration that are never applied.
+- Configuration rule: part of the rules that are useless and could be removed.
+- Total average coverage
+
+Two things are needed to generate a coverage report:
+
+1. The Settings file
+2. parameter-framework logs
+
+## How to get the Settings file
+
+Usually, you have this file at hand. But if getting the Settings file is
+painful, you may use remote-process to print it:
+
+ remote-process <host> <port> getDomainsWithSettingsXML > domains.xml
+
+## How to get PFW logs
+
+You must get the logs from the start of the parameter-framework.
+
+On Android, you should stop the process instantiating the parameter-framework,
+clear the logs, start the process and get the logs using logcat. E.g:
+
+ $ adb shell stop your_process
+ $ adb logcat -c
+ $ adb logcat > coverage.log &
+ $ adb shell start your_process
+ ... do your testing ...
+ kill the background logcat started above
+
+## How to generate the report
+
+Then execute :
+
+ $ aplog2coverage.sh -d domains.xml -e<some_regex> coverage.log -o coverageReport.html
+
+You may pass several log files.
+
+The regex (-e argument) is used to match relevant log lines: If you have
+several PFW instances running, you need to have a way to tell which instance is
+logging each line. Besides, if accelerates the parsing by eliminating
+irrelevant log lines.
+
+You may pass the optional `-f` argument to ignore some parse errors.
+
+### Limitations
+
+- Having more than one dot (".") in log paths is not supported (see the sort
+ implementation (sort -rn -k2 -t.) in aplog2coverage.sh).
+- A PFW start log line must be at the head of the oldest log: no
+ applyconfiguration or set criterion log should be found before the PFW start.
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
diff --git a/tools/xmlValidator/README.md b/tools/xmlValidator/README.md
index adc7e12..11d64a6 100644
--- a/tools/xmlValidator/README.md
+++ b/tools/xmlValidator/README.md
@@ -1,13 +1,14 @@
# xmlValidator tool
This tool can be used to check if the `.xml` files you have written are
-following the `.xsd` schemas we provided you.
-By doing so, you are *ensured* that your configuration is *fully compatible* with the `parameter-framework`.
+following the `.xsd` schemas provided by the PFW. By doing so, you are *ensured*
+that your configuration is *fully compatible* with the `parameter-framework`.
It scans all directories and subdirectories for `.xml` files and checks them
with `.xsd` from a *schemas* directory you specified for the script.
## Usage
+
To run xmlValidator, just start it from the commandline with:
python xmlValidator.py <xmlRootDirectory> <xsdDirectory>
@@ -66,8 +67,10 @@
## Install requirements
-In order to use this tool, you must have the following packages installed:
-* `python`
+In order to use this tool, you must have the following packages (these
+are the names on a debian-based distribution):
+
+* `python` (2.7 or later)
* `python-lxml`
-* `libpython2.7`
+* `libpython2.7` or later