README.md
1# parameter-framework configuration file XML Schemas
2
3These are W3C Schemas for the various configuration files.
4
5`xmllint` may be used to check for correctness, e.g:
6
7 xmllint --xinclude --noout --schema ParameterFrameworkConfiguration.xsd /path/to/your/ParameterFrameworkConfiguration.xml
8
9See `tools/xmlValidator` for a custom alternative tool.
10
11Only `ParameterFrameworkConfiguration.xsd`, `SystemClass.xsd`, `Subsystem.xsd` and
12`ConfigurableDomains.xsd` are relevant for use with xmllint: the others are
13included by these 4 XSDs.
14
15**You may refer to samples at
16<https://github.com/01org/parameter-framework-samples>.**
17
18## ParameterFrameworkConfiguration.xsd
19
20Schema for the **top-level configuration**. It contains:
21
22- A reference to the `SystemClass` (aka StructureDescription) XML file (see
23 below);
24- The list of plugins (libraries) to be used. They may be split according to
25the folder they reside in. The `Folder` attribute can either be:
26
27 - an absolute path,
28 - a relative path (relative to the execution directory),
29 - empty.
30
31 In the first two cases, the runtime loader will be asked to explicitely load
32 the libraries found in the specified folder; in the last case (empty string)
33 the runtime loader will search for the library on its own (e.g. on Linux
34 distribution this is usually `/lib`, `/usr/lib` - see `man ld.so`)
35- Optionally, a reference to the `Settings`.
36
37Attributes of `ParameterFrameworkConfiguration` are:
38
39- The `SystemClass` name (for consistency check)
40- `TuningAllowed` (whether the parameter-framework listens for commands)
41- The `ServerPort` bind Address (PATH or TCP port) on which the parameter-framework listens if
42 `TuningAllowed=true`.
43
44## SystemClass.xsd
45
46Schema for the **SystemClass associated with the top-level configuration**. It
47points to all the "Subsystem" files (see below).
48
49The `Name` attribute of the SystemClass must match the `SystemClass` attribute
50of the top-level configuration file. This name will be the first component of
51all parameters in it, i.e. if its name is "FooBar", its path is `/FooBar`. We
52will use this name in examples below.
53
54## Subsystem.xsd
55
56Schema for all **Subsystem files** (aka Structure files). These files describe the
57content and structure of the system to be managed by the parameter-framework
58and also indicate which plugin is to be used.
59
60A Subsystem has the following attribute:
61
62- `Name` (self-explanatory); again it is the base component of all parameters
63 inside it; i.e. if its name is "Spam", its path is `/FooBar/Spam`;
64- `Type`, which indicates which SubsystemBuilder is to be used (each plugin can
65 declare one or more SubsystemBuilders); it may be defined as `Virtual`, in
66 which case, no plugin will be used and the parameters won't be synchronized.
67 This is useful for debugging but may also be used for the parameter-framework
68 to act as a configurable settings database;
69- `Mapping` (optional), defines a Mapping to be inherited by all Components in
70 the Subsystem.
71
72A Subsystem *must* contain:
73
74- A `ComponentLibrary`, which may include (using `<xi:include href="xyz.xml"/>`)
75 other files containing a `<ComponentLibrary>` or a `<ComponentTypeSet>` tag.
76- An `InstanceDefinition` which instantiates the parameters and may use
77 ComponentTypes defined in the ComponentLibrary.
78
79## ConfigurableDomains.xsd
80
81Schema for the ConfigurableDomains (aka Settings files). These files contain
82the rules for applying values to parameters.
83
84Writing this file by hand is painful but it is not intended to be dealt
85with directly: instead, you may use the command-line interface (see
86`remote-process/README.md`) to set the settings and export the resulting
87Settings with the `getDomainsWithSettingsXML` command.
88