README.md: Start adding some light documentation on the policy part

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Change-Id: Ifdd6dda9dbe91e2783c4d3546e542aa2320d3707

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..753a4f6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,49 @@
+# agl-compositor
+
+## Policy
+
+The compositor contains an API useful for defining policy rules.  It contains
+the bare minimum and installs, by default, an allow-all kind of engine.
+
+Users wanted to create their own policy engine should create a specialized
+version and use `struct ivi_policy_api` where they can install their own
+callbacks.
+
+The default policy found in src/policy-default.c should more than sufficient to
+get started. Users can either re-puporse the default policy or create a new one
+entirely different, based on their needs.
+
+### Hooks
+
+These are hooks for allowing creation, committing and activation of surfaces
+(and these are ivi_policy_api::surface_create, ivi_policy_api::surface_commited,
+ivi_policy_api::surface_activate).
+
+Another hook, ivi_policy_api::policy_rule_allow_to_add can be used to control
+if policy rules (the next type) can be added or not. Finally, we have
+ivi_policy_api::policy_rule_try_event which is executed in context of policy
+rules.
+
+The current, installed hooks, permit all the above, but users can customize
+this behaviour by using some sort of database to retrieve the application name
+to compare against, or incorporate some kind of policy rule engine.
+
+
+### Policy rules
+
+Policy (injection) rules can be added using the agl-shell-policy protocol.  The
+protocol allows to define policy rules that should be executed by using the
+ivi_policy_api::policy_rule_try_event callback. These are particularly useful
+when handling state changes. The protocol supports adding new states and events
+and the default implementation has code for handling events like showing or
+hiding the application specified in the policy rule. The protocol XML file on
+contains a few more details than written here.
+
+ivi_policy_api::policy_rule_try_event callback should be adapted and correlated
+with the client shell in case additional events and states are added.
+
+By default the server side implementations adds the 'show', and 'hide' events
+and the 'start', 'stop' and 'reverse' states. An special type, assigned by
+default is 'invalid'. A state change has to be propaged from the client to the
+compositor to signal the compositor the change itself, in order to apply the
+policy rules.