doc: update and move IVI-shell README to doc

The README for the IVI-shell is completely outdated.

Update the documentation, add some more information on the IVI-shell use cases
and explain how to use and customize the IVI-shell. Also convert the file to rst
and move it to doc directory next to the kiosk-shell documentation.

Signed-off-by: Michael Tretter <m.tretter@pengutronix.de>

5 files changed, 123 insertions, 0 deletions

diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 8aa53b3e..a47bccb9 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -9,6 +9,7 @@ Welcome to Weston documentation!
    toc/libweston.rst
    toc/test-suite.rst
    toc/kiosk-shell.rst
+   toc/ivi-shell.rst
 
 Weston
 ------
diff --git a/doc/sphinx/toc/images/ivi-shell.png b/doc/sphinx/toc/images/ivi-shell.png
new file mode 100644
index 00000000..87ff7a36
--- /dev/null
+++ b/doc/sphinx/toc/images/ivi-shell.png
diff --git a/doc/sphinx/toc/images/meson.build b/doc/sphinx/toc/images/meson.build
new file mode 100644
index 00000000..c73a8c60
--- /dev/null
+++ b/doc/sphinx/toc/images/meson.build
@@ -0,0 +1,9 @@
+# Sphinx does not know look for these files in the source directory, so
+# they must be copied to the build directory.
+files = [
+	'ivi-shell.png',
+]
+
+foreach file : files
+	configure_file(input: file, output: file, copy: true)
+endforeach
diff --git a/doc/sphinx/toc/ivi-shell.rst b/doc/sphinx/toc/ivi-shell.rst
new file mode 100644
index 00000000..42eb5fe5
--- /dev/null
+++ b/doc/sphinx/toc/ivi-shell.rst
@@ -0,0 +1,111 @@
+Weston IVI-shell
+================
+
+Weston's IVI-shell is a highly customizable shell targeted at use cases which
+need custom control over the shell's window layout with one or more applications
+without interactive configuration of the layout by the user.
+
+Example use cases for the IVI-shell are IVI applications or industrial human
+machine interfaces. In general, whenever the user interface requires the exact
+positioning of multiple application surfaces on one or more screens.
+
+The IVI-shell also provides a means for applications to identify themselves to
+the shell by application IDs via the ivi_application Wayland protocol.
+
+IVI-shell client protocol
+-------------------------
+
+Wayland clients can implement the ``ivi_application`` Wayland protocol, which
+allows them to specify an ``ivi_id`` to allow the IVI controller to identify the
+application. This allows the controller to implement special behavior for
+well-known applications.
+
+The IVI-shell is able to also handle clients that use the ``xdg-shell``
+protocol, but in these cases the IVI-shell needs other means to identify client
+applications.
+
+See ``ivi-application.xml`` for the protocol specification.
+
+IVI-shell Weston modules
+------------------------
+
+The IVI-shell consists of two main components: The ``ivi-shell.so`` and custom
+IVI controller (with the ``hmi-controller.so`` example implementation).
+
+The ``ivi-shell.so`` is responsible for handling the application IDs and for
+providing abstractions to configure the window layout via the
+``ivi_layout_interface``. This interface is discussed in `IVI-shell compositor
+implementation`.
+
+The IVI controller uses the ``ivi_layout_interface`` to implement a window
+manager and is responsible for configuring the window layout, i.e. the position
+of the applications on the screens.
+
+Due to this separation, both modules must be loaded in your ``weston.ini`` to
+use the IVI-shell.
+
+.. code-block:: ini
+
+  [core]
+  shell=ivi-shell.so
+  modules=hmi-controller.so
+
+If you are using your custom controller, replace ``hmi-controller.so`` with the
+name of your own controller module.
+
+.. figure:: images/ivi-shell.png
+   :alt: IVI-shell architecture overview
+
+Controlling the IVI-shell
+-------------------------
+
+The IVI-shell provides the ``ivi_layout_interface`` API that a controller must
+use to control the window layout of the IVI-shell. See
+``ivi-shell/ivi-layout-export.h`` for the definition of this API.
+
+For the initial configuration, the controller has to create at least one
+``ivi_layout_layer`` and add the ``ivi_layout_layer`` to a ``weston_output``.
+The layers allow to group multiple applications surfaces and control them
+together and are the main mechanism to group and organize surfaces. These are
+always necessary to show something using the IVI-shell. The IVI-shell will
+internally create an ``ivi_layout_screen``, but a controller always uses the
+``weston_output`` directly.
+
+To get control over the client surfaces, the controller must use notifiers that
+trigger whenever there are changes to the client surfaces.  The client surfaces
+then show up as ``ivi_layout_surface``.  These have an ID, which allows the
+controller to identify the surface and reconfigure the window layout
+accordingly.
+
+The controller must add the ``ivi_layout_surface`` to an ``ivi_layout_layer``
+and configure it's position and z-order wrt. the other surfaces in the layer.
+Otherwise, the newly added surface will not show up on the screen.
+
+The IVI-shell will internally create an ``ivi_layout_view`` for each layer that
+the surface was added to. However, the views are not provided to the IVI
+controller.
+
+After configuring all expected changes, the controller must call the
+``commit_changes`` to atomically update the display layout.
+
+IVI-shell example implementation
+--------------------------------
+
+The IVI-shell comes with an example implementation of an IVI controller -- the
+`hmi-controller`. The hmi-controller will usually replaced by a custom
+implementation that implements the use-case-specific behavior.
+
+The hmi-controller is split into two parts:
+
+The ``hmi-controller.so`` is a Weston Plugin that uses the
+``ivi_layout_interface`` to perform the window manager tasks. It allows some
+reconfiguration of the window layout via the ``ivi_hmi_controller`` protocol.
+Other implementations may keep all window management inside the module or may
+expose even more window management via a custom protocol to an external process.
+
+The ``weston-ivi-shell-user-interface`` is an example hmi-controller helper
+client that serves as a user interface for controlling the hmi-controller.
+
+The hmi-controller can be customized using the ``[ivi-shell]`` section in the
+``weston.ini``. An example configuration will be generated in
+``<build_dir>/ivi-shell/weston.ini``.
diff --git a/doc/sphinx/toc/meson.build b/doc/sphinx/toc/meson.build
index b7190f78..4c638411 100644
--- a/doc/sphinx/toc/meson.build
+++ b/doc/sphinx/toc/meson.build
@@ -1,6 +1,7 @@
 # you need to add here any files you add to the toc directory as well
 files = [
 	'kiosk-shell.rst',
+	'ivi-shell.rst',
 	'running-weston.rst',
 	'libweston.rst',
 	'test-suite.rst',
@@ -11,4 +12,5 @@ foreach file : files
 	configure_file(input: file, output: file, copy: true)
 endforeach
 
+subdir('images')
 subdir('libweston')