unit_control: add documentation

Change-Id: I49ea3fa46cc579af72119cdcb483bf4838e04c27
Signed-off-by: Paweł Szewczyk <p.szewczyk@samsung.com>

diff --git a/doc/unit_control_api.rst b/doc/unit_control_api.rst
new file mode 100644 (file)
index 0000000..4b7333c
--- /dev/null
+++ b/doc/unit_control_api.rst
@@ -0,0 +1,65 @@
+Unit Control API
+================
+
+Overview
+--------
+
+This set of modules provides API for controling systemd units by unprivileged programs.
+
+Listener
+--------
+
+The unit_control_api listener module is needed for exposing DBUS API. There is no configuration needed.
+
+Dbus API
+~~~~~~~~
+
+Service      org.tizen.Activationd
+Object path  /org/tizen/activationd
+Interface    org.tizen.Activationd
+
+Methods
+    Stop(s: unit)
+      Stop a unit
+
+    Start(s: unit)
+      Start a unit
+
+    Restart(s: unit)
+      Restart a unit
+
+
+Decision maker
+--------------
+
+The unit_control_dm module provides the policy mechanism for deciding which units can be controlled.
+If the policy allows it, it executes unit-related actions (Stop, Start, Restart).
+
+Configuration
+~~~~~~~~~~~~~
+
+The configuration of unit_control_dm configuration should provide a whitelist of systemd units.
+These units are allowed to be controlled by unit-control mechanism.
+
+whitelist
+  A list of systemd unit names to be controlled by this module.
+  Can be names of templates, e.g. "foo@.bar", in which case all instances of this template (foo@<instance>.bar)
+  can be controlled.
+
+Pattern matching
+~~~~~~~~~~~~~
+
+A whitelist may be specified in one of following formats:
+  - a direct name of a unit, i.e. foo.service
+  - a direct name of an instance of a unit, i.e. foo@bar.service
+  - a wildcarded template, i.e. foo@.service (stop and restart only) - in this case a method calls are performed on
+    all running instances of a matching unit. If any of those method calls fails, an errno-style value is attached
+    to an error reply. However, in that case a corresponding method call is performed on all matching instances.
+
+Return values
+~~~~~~~~~~~~~
+
+A successful method call should return a single "ok" string as a reply. If anything goes wrong, an error is returned
+as a reply with an errno-style value attached.
+
+