Re-order doc chapters

Change-Id: I44cf2054fa06816480e26fc19b45c6f8a464a708
Signed-off-by: Sebastien Douheret <sebastien.douheret@iot.bzh>

1 files changed, 507 insertions, 0 deletions

diff --git a/docs/2.2-config.xml.md b/docs/2.2-config.xml.md
new file mode 100644
index 0000000..cccedd4
--- /dev/null
+++ b/docs/2.2-config.xml.md
@@ -0,0 +1,507 @@
+Configuration file - config.xml
+===============================
+
+The widgets are described by the W3C's technical recommendations
+[Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig]
+ that specifies the configuration file **config.xml**.
+
+Overview
+--------
+
+The file **config.xml** describes important data of the application
+to the framework:
+
+- the unique identifier of the application
+- the name of the application
+- the type of the application
+- the icon of the application
+- the permissions linked to the application
+- the services and dependencies of the application
+
+The file MUST be at the root of the widget and MUST be case sensitively name
+***config.xml***.
+
+The file **config.xml** is a XML file described by the document
+[widgets].
+
+Here is the example of the config file for the QML application SmartHome.
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<widget xmlns="http://www.w3.org/ns/widgets" id="smarthome" version="0.1">
+  <name>SmartHome</name>
+  <icon src="smarthome.png"/>
+  <content src="qml/smarthome/smarthome.qml" type="text/vnd.qt.qml"/>
+  <description>This is the Smarthome QML demo application. It shows some user interfaces for controlling an
+automated house. The user interface is completely done with QML.</description>
+  <author>Qt team</author>
+  <license>GPL</license>
+</widget>
+```
+
+The most important items are:
+
+- **<widget id="......"\>**: gives the id of the widget. It must be unique.
+
+- **<widget version="......"\>**: gives the version of the widget
+
+- **<icon src="..."\>**: gives a path to the icon of the application
+  (can be repeated with different sizes)
+
+- **<content src="..." type="..."\>**: this indicates the entry point and its type.
+
+Standard elements of "config.xml"
+---------------------------------
+
+### The element widget
+
+#### the attribute id of widget
+
+The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique.
+
+Values for *id* are any non empty string containing only latin letters,
+arabic digits, and the three characters '.' (dot), '-' (dash) and
+'\_' (underscore).
+
+Authors can use a mnemonic id or can pick a unique id using
+command **uuid** or **uuidgen**.
+
+### the attribute version of widget
+
+The attribute *version* is mandatory (for version 2.x, blowfish).
+
+Values for *version* are any non empty string containing only latin letters,
+arabic digits, and the three characters '.' (dot), '-' (dash) and
+'\_' (underscore).
+
+Version values are dot separated fields MAJOR.MINOR.REVISION.
+Such version would preferabily follow guidelines of
+[semantic versionning][semantic-version].
+
+### The element content
+
+The element *content* is mandatory (for version 2.x, blowfish) and must designate a file
+(subject to localisation) with its attribute *src*.
+
+The content designed depends on its type. See below for the known types.
+
+### The element icon
+
+The element *icon* is mandatory (for version 2.x, blowfish) and must
+be unique. It must designate an image file with its attribute *src*.
+
+AGL features
+------------
+
+The AGL framework uses the feature tag for specifying security and binding
+requirement of the widget.
+
+Since the migration of the framework to leverage systemd power,
+the features are of important use to:
+
+ - declare more than just an application
+ - declare the expected dependencies
+ - declare the expected permissions
+ - declare the exported apis
+
+The specification of [widgets][widgets] is intentded to describe
+only one application. In the present case, we expect to describe
+more than just an application. For example, a publisher could
+provide a widget containing a service, an application for tuning
+that service, an application that leverage the service.
+Here, the term of service means a background application that
+runs without IHM and whose public api can be accessed by other
+applications.
+
+So the features are used to describe each of the possible
+units of widgets. The "standard" unit in the
+meaning of [widgets][widgets] is called the "main" unit.
+
+### feature name="urn:AGL:widget:required-api"
+
+List of the api required by the widget.
+
+Each required api must be explicited using a <param> entry.
+
+Example:
+```xml
+<feature name="urn:AGL:widget:required-api">
+  <param name="#target" value="main" />>
+  <param name="gps" value="auto" />
+  <param name="afm-main" value="link" />
+</feature>
+```
+
+This will be *virtually* translated for mustaches to the JSON
+```json
+"required-api": [
+   { "name": "gps", "value": "auto" },
+   { "name": "afm-main", "value": "link" }
+ ]
+```
+
+#### param name="#target"
+
+OPTIONAL
+
+Declares the name of the unit requiring the listed apis.
+Only one instance of the param "#target" is allowed.
+When there is not instance of this param, it behave as if
+the target main was specified.
+
+#### param name=[required api name]
+
+The name is the name of the required API.
+
+The value describes how to connect to the required api.
+It is either:
+
+ - local:
+
+   The binding is a local shared object.
+   In that case, the name is the relative path of the
+   shared object to be loaded.
+
+ - auto:
+
+   The framework set automatically the kind of
+   the connection to the API
+
+ - ws:
+
+   The framework connect using internal websockets
+
+ - dbus:
+
+   The framework connect using internal dbus
+
+ - link:
+
+   The framework connect in memory by dinamically linking
+
+ - cloud: [PROPOSAL - NOT IMPLEMENTED]
+
+   The framework connect externally using websock.
+   In that case, the name includes data to access the service.
+   Example: `<param name="log:https://oic@agl.iot.bzh/cloud/log" value="cloud" />`
+
+### feature name="urn:AGL:widget:required-permission"
+
+List of the permissions required by the unit.
+
+Each required permission must be explicited using a <param> entry.
+
+Example:
+
+```xml
+  <feature name="urn:AGL:widget:required-permission">
+    <param name="#target" value="geoloc" />
+    <param name="urn:AGL:permission:real-time" value="required" />
+    <param name="urn:AGL:permission:syscall:*" value="required" />
+  </feature>
+```
+
+This will be *virtually* translated for mustaches to the JSON
+
+```json
+"required-permission":{
+  "urn:AGL:permission:real-time":{
+    "name":"urn:AGL:permission:real-time",
+    "value":"required"
+  },
+  "urn:AGL:permission:syscall:*":{
+    "name":"urn:AGL:permission:syscall:*",
+    "value":"required"
+  }
+}
+```
+
+#### param name="#target"
+
+OPTIONAL
+
+Declares the name of the unit requiring the listed permissions.
+Only one instance of the param "#target" is allowed.
+When there is not instance of this param, it behave as if
+the target main was specified.
+
+#### param name=[required permission name]
+
+The value is either:
+
+- required: the permission is mandatorily needed except if the feature
+isn't required (required="false") and in that case it is optional.
+- optional: the permission is optional
+
+
+### feature name="urn:AGL:widget:provided-unit"
+
+This feature is made for declaring new units
+for the widget. Using this feature, a software publisher
+can provide more than one application in the same widget.
+
+Example:
+```xml
+  <feature name="urn:AGL:widget:provided-unit">
+    <param name="#target" value="geoloc" />
+    <param name="description" value="binding of name geoloc" />
+    <param name="content.src" value="index.html" />
+    <param name="content.type" value="application/vnd.agl.service" />
+  </feature>
+```
+
+This will be *virtually* translated for mustaches to the JSON
+```json
+    {
+      "#target":"geoloc",
+      "description":"binding of name geoloc",
+      "content":{
+        "src":"index.html",
+        "type":"application\/vnd.agl.service"
+      },
+      ...
+    }
+```
+
+#### param name="#target"
+
+REQUIRED
+
+Declares the name of the unit. The default unit, the unit
+of the main of the widget, has the name "main". The value
+given here must be unique within the widget file. It will
+be used in other places of the widget config.xml file to
+designate the unit.
+
+Only one instance of the param "#target" is allowed.
+The value can't be "main".
+
+#### param name="content.type"
+
+REQUIRED
+
+The mimetype of the provided unit.
+
+#### param name="content.src"
+
+A path to the
+
+#### other parameters
+
+The items that can be set for the main unit
+can also be set using the params if needed.
+
+ - description
+ - name.content
+ - name.short
+ - ...
+
+
+### feature name="urn:AGL:widget:provided-api"
+
+Use this feature for exporting one or more API of a unit
+to other widgets of the platform.
+
+This feature is an important feature of the framework.
+
+Example:
+
+```xml
+  <feature name="urn:AGL:widget:provided-api">
+    <param name="#target" value="geoloc" />
+    <param name="geoloc" value="auto" />
+    <param name="moonloc" value="auto" />
+  </feature>
+```
+
+This will be *virtually* translated for mustaches to the JSON
+
+```json
+      "provided-api":[
+        {
+          "name":"geoloc",
+          "value":"auto"
+        },
+        {
+          "name":"moonloc",
+          "value":"auto"
+        }
+      ],
+```
+
+#### param name="#target"
+
+
+OPTIONAL
+
+Declares the name of the unit exporting the listed apis.
+Only one instance of the param "#target" is allowed.
+When there is not instance of this param, it behave as if
+the target main was specified.
+
+
+#### param name=[name of exported api]
+
+The name give the name of the api that is exported.
+
+The value is one of the following values:
+
+ - ws:
+
+   export the api using UNIX websocket
+
+ - dbus:
+
+   export the API using dbus
+
+ - auto:
+
+   export the api using the default method(s).
+
+
+Known content types
+-------------------
+
+The configuration file ***/etc/afm/afm-unit.conf*** defines
+how to create systemd units for widgets.
+
+Known types for the type of content are:
+
+- ***text/html***:
+   HTML application,
+   content.src designates the home page of the application
+
+- ***application/vnd.agl.native***
+   AGL compatible native,
+   content.src designates the relative path of the binary.
+
+- ***application/vnd.agl.service***:
+   AGL service, content.src is not used.
+
+- ***application/x-executable***:
+   Native application,
+   content.src designates the relative path of the binary.
+   For such application, only security setup is made.
+
+Adding more types is easy, it just need to edit the configuration
+file ***afm-unit.conf***.
+
+### Older content type currently not supported at the moment.
+
+This types were defined previously when the framework was not
+leveraging systemd. The transition to systemd let these types
+out at the moment.
+
+- ***application/vnd.agl.url***
+- ***text/vnd.qt.qml***, ***application/vnd.agl.qml***
+- ***application/vnd.agl.qml.hybrid***
+- ***application/vnd.agl.html.hybrid***
+
+
+The configuration file afm-unit.conf
+====================================
+
+The integration of the framework with systemd
+mainly consists of creating the systemd unit
+files corresponding to the need and requirements
+of the installed widgets.
+
+This configuration file named `afm-unit.conf` installed
+on the system wiht the path `/etc/afm/afm-unit.conf`
+describes how to generate all units from the *config.xml*
+configuration files of widgets. The description uses an extended
+version of the templating formalism of [mustache][]
+to describes all the units.
+
+Let present how it works using the following diagram that
+describes graphically the workflow of creating the unit
+files for systemd `afm-unit.conf` from the configuration
+file of the widget `config.xml`:
+
+![make-units][make-units]
+
+In a first step, and because [mustache][] is intended
+to work on JSON representations, the configuration file is
+translated to an internal JSON representation. This
+representation is shown along the examples of the documentation
+of the config files of widgets.
+
+In a second step, the mustache template `afm-unit.conf`
+is instanciated using the C library [mustach][] that follows
+the rules of [mustache][mustache] and with all its available
+extensions:
+
+ - use of colon (:) for explicit substitution
+ - test of values with = or =!
+
+In a third step, the result of instanciating `afm-unit.conf`
+for the widget is splited in units. To achieve that goal,
+the lines containing specific directives are searched.
+Any directive occupy one full line. The directives are:
+
+  - %nl
+
+    Produce an empty line at the end
+
+  - %begin systemd-unit
+  - %end systemd-unit
+
+    Delimit the produced unit, its begin and its end
+
+  - %systemd-unit user
+  - %systemd-unit system
+
+    Tells the kind of unit (user/system)
+
+  - %systemd-unit service NAME
+  - %systemd-unit socket NAME
+
+    Gives the name and type (service or socket) of the unit.
+    The extension is automatically computed from the type
+    and must not be set in the name.
+
+  - %systemd-unit wanted-by NAME
+
+    Tells to install a link to the unit in the wants of NAME
+
+Then the computed units are then written to the filesystem
+and inserted in systemd.
+
+The generated unit files will contain variables for internal
+use of the framework. These variables are starting with `X-AFM-`.
+The variables starting with `X-AFM-` but not with `X-AFM--` are
+the public variables. These variables will be returned by the
+framework as the details of an application (see **afm-util detail ...**).
+
+Variables starting with `X-AFM--` are private to the framework.
+By example, the variable  `X-AFM--http-port` is used to
+record the allocated port for applications.
+
+
+[mustach]:          https://gitlab.com/jobol/mustach                                "basic C implementation of mustache"
+[mustache]:         http://mustache.github.io/mustache.5.html                       "mustache - Logic-less templates"
+[make-units]:       pictures/make-units.svg
+[widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
+[widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
+[libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
+[app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
+
+
+[meta-intel]:       https://github.com/01org/meta-intel-iot-security                "A collection of layers providing security technologies"
+[widgets]:          http://www.w3.org/TR/widgets                                    "Packaged Web Apps"
+[widgets-digsig]:   http://www.w3.org/TR/widgets-digsig                             "XML Digital Signatures for Widgets"
+[libxml2]:          http://xmlsoft.org/html/index.html                              "libxml2"
+[openssl]:          https://www.openssl.org                                         "OpenSSL"
+[xmlsec]:           https://www.aleksey.com/xmlsec                                  "XMLSec"
+[json-c]:           https://github.com/json-c/json-c                                "JSON-c"
+[d-bus]:            http://www.freedesktop.org/wiki/Software/dbus                   "D-Bus"
+[libzip]:           http://www.nih.at/libzip                                        "libzip"
+[cmake]:            https://cmake.org                                               "CMake"
+[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager"
+[app-manifest]:     http://www.w3.org/TR/appmanifest                                "Web App Manifest"
+[tizen-security]:   https://wiki.tizen.org/wiki/Security                            "Tizen security home page"
+[tizen-secu-3]:     https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview         "Tizen 3 security overview"
+[semantic-version]: http://semver.org/                                              "Semantic versionning"
+
+
+