diff options
| -rw-r--r-- | README.md | 68 | ||||
| -rw-r--r-- | Schemas/README.md | 48 | ||||
| -rw-r--r-- | parameter/README.md | 4 | ||||
| -rw-r--r-- | remote-process/README.md | 31 | ||||
| -rw-r--r-- | remote-processor/README.md | 4 | ||||
| -rw-r--r-- | skeleton-subsystem/README.md | 7 | ||||
| -rw-r--r-- | test/test-platform/README.md | 33 | ||||
| -rw-r--r-- | tools/coverage/README.md | 61 | ||||
| -rw-r--r-- | tools/xmlGenerator/README.md | 223 | ||||
| -rw-r--r-- | tools/xmlValidator/README.md | 13 |
10 files changed, 480 insertions, 12 deletions
@@ -1,10 +1,62 @@ # parameter-framework -tl;dr: compilation instructions are at the end - ## Introduction -WIP +The parameter-framework is a plugin-based and rule-based framework for handling +parameters. This means that you can: + +1. Describe your system's structure and its parameters (in XML) - aka. **What**; +2. Write (in C++) or reuse a backend (aka. plugin) for accessing the parameters +that you just described - aka. **How**; +3. Define (in XML or in a domain-specific-language) conditions/rules upon which +a given parameter must take a given value - aka. **When**. + + + +### Usage examples + +#### Alsa controls on embedded platforms + +The parameter-framework can be used to set the value of alsa controls +(switches, volumes, etc.) on smartphones/tablets based on parameter-framework +rules (in this example, they transcribe use-cases). For accessing parameters +(i.e. alsa controls), you may use the +[alsa plugin](https://github.com/01org/parameter-framework-plugins-alsa). + +#### Parameters in files + +The [filesystem plugin](https://github.com/01org/parameter-framework-plugins-filesystem) +can be used to write parameters in files. This is particularly useful for +files in `/sys` managing GPIOs. + +### More details + +The parameter-framework's core comes in the form of a shared library. Its +client has to provide: + +- configuration files describing the structure of the system to be managed by + the parameter-framework and what plugins it must use to read/write into each + subsystem; +- a list of criteria (representing the state of the client) and their possible + values; +- configuration files describing the value that each part of the system (aka + parameter) must take - this is done by writing rules based on the criteria + described above. + +At runtime, the most usual communication between the client and the +parameter-framework are: + +1. The update of *criteria* (that are used in the rules introduced above) and +2. Update all relevant parameters according to the new criteria values. The + parameter-framework uses the appropriate backend for writing the values in + each underlying subsystem. + +The parameter-framework comes with several tools, including a command-line +interface: `remote-process`. + +## Going further + +See [the wiki on github](https://github.com/01org/parameter-framework/wiki). ## Compiling @@ -12,4 +64,12 @@ Run `cmake .` then `make`. You may then install libraries, headers and binaries with `make install`. By default, they are installed under `/usr/local` on unix OSes; if you want to install them under a custom directory, you may do so by passing it to the `cmake .` command; e.g. -`cmake -DCMAKE_INSTALL_PREFIX=/path/to/custom/install .`. + + cmake -DCMAKE_INSTALL_PREFIX=/path/to/custom/install . + +Also, CMake can build a project out-of-tree, which is the recommended method: + + mkdir /path/to/build/directory + cd /path/to/build/directory + cmake /path/to/parameter-framework/sources + make diff --git a/Schemas/README.md b/Schemas/README.md new file mode 100644 index 0000000..3563b4b --- /dev/null +++ b/Schemas/README.md @@ -0,0 +1,48 @@ +# parameter-framework configuration file XML Schemas + +These are W3C Schemas for the various configuration files. + +`xmllint` may be used to check for correctness, e.g: + + xmllint --xinclude --noout --schema ParameterFrameworkConfiguration.xsd /path/to/your/ParameterFrameworkConfiguration.xml + +See `tools/xmlValidator` for a custom alternative tool. + +Only `ParameterFrameworkConfiguration.xsd`, `SystemClass.xsd`, `Subsystem.xsd` and +`ConfigurableDomains.xsd` are relevant for use with xmllint: the others are +included by these 4 XSDs. + +You may refer to samples at +<https://github.com/01org/parameter-framework-samples>. + +## ParameterFrameworkConfiguration.xsd + +Schema for the top-level configuration. It contains: + +- A reference to the `SystemClass` (aka StructureDescription) XML file (see + below); +- The list of plugins to be used; +- Optionally, a reference to the `Settings`. + +Attributes of `ParameterFrameworkConfiguration` are: + +- The `SystemClass` name (for consistency check) +- The `TuningMode` (whether the parameter-framework listens for commands) +- The `ServerPort` on which the parameter-framework listens if + `TuningMode=true`. + +## SystemClass.xsd + +Schema for the SystemClass associated with the top-level configuration. It +points to all the "Subsystem" files (see below). + +## Subsystem.xsd + +Schema for all Subsystem files (aka Structure files). These files describe the +content and structure of the system to be managed by the parameter-framework +and also indicate which plugin is to be used. + +## ConfigurableDomains.xsd + +Schema for the ConfigurableDomains (aka Settings files). These files contain +the rules for applying values to parameters. diff --git a/parameter/README.md b/parameter/README.md new file mode 100644 index 0000000..1c74e17 --- /dev/null +++ b/parameter/README.md @@ -0,0 +1,4 @@ +# parameter-framework's core + +The corresponding doxygen can be found here: +<http://01org.github.io/parameter-framework> diff --git a/remote-process/README.md b/remote-process/README.md new file mode 100644 index 0000000..128dc3f --- /dev/null +++ b/remote-process/README.md @@ -0,0 +1,31 @@ +# remote-process + +`remote-process` is an executable used to communicate with an instance of the +parameter-framework through a TCP socket. It is only possible if the +parameter-framework's configuration allows it (`TuningAllowed="true"` in the +ParameterFrameworkConfiguration.xml) and if the port is also defined in the +configuration (by the `ServerPort` attribute): + +For instance, if your parameter-framework configuration starts with: + + <ParameterFrameworkConfiguration SystemClassName="..." ServerPort="5000" TuningAllowed="true"> + +then, it listens on port 5000. + +remote-process may also be used to communicate with test-platform +(see test/test-platform/README.md) thanks to test-platform being a minimal +parameter-framework client. + +## Syntax + + remote-process <host> <port> <command> + +You can get all available commands with the `help` command. + +You may also run a batch of commands by passing them on remote-process' +standard input: + + remote-process <host> <port> < file + +You should not use this feature in an interactive mode, because the +communication may timeout if you're typing your commands too slowly. diff --git a/remote-processor/README.md b/remote-processor/README.md new file mode 100644 index 0000000..2fd56e2 --- /dev/null +++ b/remote-processor/README.md @@ -0,0 +1,4 @@ +# libremote-processor + +This library is used by both the parameter-framework library (server) and the +remote-process tool (client). diff --git a/skeleton-subsystem/README.md b/skeleton-subsystem/README.md index 0d90f30..e5ee0b2 100644 --- a/skeleton-subsystem/README.md +++ b/skeleton-subsystem/README.md @@ -2,11 +2,12 @@ This is a skeleton plugin i.e. the minimal plugin boilerplate. -It adds an owner and message mapping key and print it when reading or writing -the parameter. +It adds an `owner` and `message` mapping key and print it when reading or +writing the parameter. ## Usage It has no purpose: it only serves as a template and the `make install` target does not install it. If you want to see a real-life plugin and makefiles, see -<https://github.com/01org/parameter-framework-plugins-alsa> instead. +<https://github.com/01org/parameter-framework-plugins-alsa> or +<https://github.com/01org/parameter-framework-plugins-filesystem> instead. diff --git a/test/test-platform/README.md b/test/test-platform/README.md new file mode 100644 index 0000000..4e3cab8 --- /dev/null +++ b/test/test-platform/README.md @@ -0,0 +1,33 @@ +# test-platform + +Test-platform is a little executable that can instantiate a parameter-framework +with custom criteria and full control over criteria states. It also serves +as an example of a parameter-framework client. + +It offers the possibility to : + +- Give the parameter-framework configuration xml +- Create criteria from a name, a type (exclusive or inclusive), states (the + state number or a state name list) +- Start a parameter-framework instance +- Change criteria states and apply configurations + +## Usage + +Start it with: + + test-platform [-d] </path/to/ParameterFrameworkConfiguration.xml> [port, defaults to 5001] + +(The optional `-d` option daemonizes test-platform). + +Then, you may send commands to the test-platform using remote-process; e.g: + + remote-process localhost 5001 help + remote-process localhost 5001 start + +## Known issues + +- The path to the configuration file must contain at least a `/`. Thus, if you +want to refer to a file in the current directory, you should write: + + test-platform ./ParameterFrameworkConfiguration.xml 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 |