From f811b7b53c0c2f0d4320c70230e609619c5087c1 Mon Sep 17 00:00:00 2001 From: David Wagner Date: Thu, 6 Mar 2014 14:58:29 +0100 Subject: 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 --- tools/coverage/README.md | 61 ++++++++++++ tools/xmlGenerator/README.md | 223 +++++++++++++++++++++++++++++++++++++++++++ tools/xmlValidator/README.md | 13 ++- 3 files changed, 292 insertions(+), 5 deletions(-) create mode 100644 tools/coverage/README.md create mode 100644 tools/xmlGenerator/README.md (limited to 'tools') 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 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 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] + +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 @@ -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 -- cgit v1.1