From 9883735c1ce77a6b2061a39ded4cc3b94e019a73 Mon Sep 17 00:00:00 2001
From: Peter Hutterer <peter.hutterer@who-t.net>
Date: Thu, 28 May 2015 09:33:07 +1000
Subject: [PATCH] README: add two diagrams to outline the stack

Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
---
 README.txt                        | 21 +++++++++++++++++++++
 doc/Makefile.am                   |  2 ++
 doc/dot/libinput-stack-wayland.gv | 17 +++++++++++++++++
 doc/dot/libinput-stack-xorg.gv    | 19 +++++++++++++++++++
 4 files changed, 59 insertions(+)
 create mode 100644 doc/dot/libinput-stack-wayland.gv
 create mode 100644 doc/dot/libinput-stack-xorg.gv

diff --git a/README.txt b/README.txt
index 3c7a5d5..07e8fa3 100644
--- a/README.txt
+++ b/README.txt
@@ -16,6 +16,27 @@ libinput originates from
 [weston](http://cgit.freedesktop.org/wayland/weston/), the Wayland reference
 compositor.
 
+Architecture
+------------
+
+libinput is not used directly by applications, rather it is used by the
+xf86-input-libinput X.Org driver or wayland compositors. The typical
+software stack for a system running Wayland is:
+
+@dotfile libinput-stack-wayland.gv
+
+Where the Wayland compositor may be Weston, mutter, KWin, etc. Note that
+Wayland encourages the use of toolkits, so the Wayland client (your
+application) does not usually talk directly to the compositor but rather
+employs a toolkit (e.g. GTK) to do so.
+
+The simplified software stack for a system running X.Org is:
+
+@dotfile libinput-stack-xorg.gv
+
+Again, on a modern system the application does not usually talk directly to
+the X server using Xlib but rather employs a toolkit to do so.
+
 Source code
 -----------
 
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ed2f72f..181fe2e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -24,6 +24,8 @@ header_files = \
 diagram_files = \
 	$(srcdir)/dot/seats-sketch.gv \
 	$(srcdir)/dot/seats-sketch-libinput.gv \
+	$(srcdir)/dot/libinput-stack-wayland.gv \
+	$(srcdir)/dot/libinput-stack-xorg.gv \
 	$(srcdir)/svg/software-buttons.svg \
 	$(srcdir)/svg/clickfinger.svg \
 	$(srcdir)/svg/button-scrolling.svg \
diff --git a/doc/dot/libinput-stack-wayland.gv b/doc/dot/libinput-stack-wayland.gv
new file mode 100644
index 0000000..20b334e
--- /dev/null
+++ b/doc/dot/libinput-stack-wayland.gv
@@ -0,0 +1,17 @@
+digraph stack
+{
+  rankdir="LR";
+  node [
+    shape="box";
+  ]
+
+  kernel [label="Kernel"];
+
+  libinput;
+  compositor [label="Wayland Compositor"];
+  client [label="Wayland Client"];
+
+  kernel -> libinput
+  libinput -> compositor
+  compositor -> client
+}
diff --git a/doc/dot/libinput-stack-xorg.gv b/doc/dot/libinput-stack-xorg.gv
new file mode 100644
index 0000000..e50f241
--- /dev/null
+++ b/doc/dot/libinput-stack-xorg.gv
@@ -0,0 +1,19 @@
+digraph stack
+{
+  rankdir="LR";
+  node [
+    shape="box";
+  ]
+
+  kernel [label="Kernel"];
+
+  libinput;
+  xf86libinput [label="xf86-input-libinput"];
+  xserver [label="X Server"];
+  client [label="X11 client"];
+
+  kernel -> libinput
+  libinput -> xf86libinput
+  xf86libinput -> xserver
+  xserver -> client
+}
-- 
2.7.4