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>

3 files changed, 292 insertions, 5 deletions

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 @@ And we will get the following output on the commandline:
 
 
 ## 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