[PATCH v2 8/8] drm/xen-front: Provide kernel documentation

[Oleksandr Andrushchenko]

From: Oleksandr Andrushchenko <oleksandr_andrushchenko@xxxxxxxx>

Provide kernel documentation for the Xen para-virtualized
frontend DRM driver.

Signed-off-by: Oleksandr Andrushchenko <oleksandr_andrushchenko@xxxxxxxx>
---
 Documentation/gpu/index.rst     |  1 +
 Documentation/gpu/xen-front.rst | 77 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100644 Documentation/gpu/xen-front.rst

diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst
index c36586dad29d..e31684af0a20 100644
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -20,6 +20,7 @@ Linux GPU Driver Developer's Guide
    vga-switcheroo
    vgaarbiter
    bridge/dw-hdmi
+   xen-front
    todo
 
 .. only::  subproject and html
diff --git a/Documentation/gpu/xen-front.rst b/Documentation/gpu/xen-front.rst
new file mode 100644
index 000000000000..6ac0b75373c4
--- /dev/null
+++ b/Documentation/gpu/xen-front.rst
@@ -0,0 +1,77 @@
+====================================
+Xen para-virtualized frontend driver
+====================================
+This frontend driver implements Xen para-virtualized display
+according to the display protocol described at
+include/xen/interface/io/displif.h
+
+Driver modes of operation in terms of display buffers used
+==========================================================
+
+Depending on the requirements for the para-virtualized environment, namely
+requirements dictated by the accompanying DRM/(v)GPU drivers running in both
+host and guest environments, number of operating modes of para-virtualized
+display driver are supported:
+
+- display buffers can be allocated by either frontend driver or backend
+- display buffers can be allocated to be contiguous in memory or not
+
+Note! Frontend driver itself has no dependency on contiguous memory for
+its operation.
+
+Buffers allocated by the frontend driver
+----------------------------------------
+
+The below modes of operation are configured at compile-time via
+frontend driver's kernel configuration:
+
+With GEM CMA helpers
+~~~~~~~~~~~~~~~~~~~~
+ This use-case is useful when used with accompanying DRM/vGPU driver in
+ guest domain which was designed to only work with contiguous buffers,
+ e.g. DRM driver based on GEM CMA helpers: such drivers can only import
+ contiguous PRIME buffers, thus requiring frontend driver to provide
+ such. In order to implement this mode of operation para-virtualized
+ frontend driver can be configured to use GEM CMA helpers.
+
+Without GEM CMA helpers
+~~~~~~~~~~~~~~~~~~~~~~~
+ If accompanying drivers can cope with non-contiguous memory then, to
+ lower pressure on CMA subsystem of the kernel, driver can allocate
+ buffers from system memory.
+
+ Note! If used with accompanying DRM/(v)GPU drivers this mode of operation
+ may require IOMMU support on the platform, so accompanying DRM/vGPU
+ hardware can still reach display buffer memory while importing PRIME
+ buffers from the frontend driver.
+
+Buffers allocated by the backend
+--------------------------------
+
+This mode of operation is run-time configured via guest domain configuration
+through XenStore entries.
+
+For systems which do not provide IOMMU support, but having specific
+requirements for display buffers it is possible to allocate such buffers
+at backend side and share those with the frontend.
+For example, if host domain is 1:1 mapped and has DRM/GPU hardware expecting
+physically contiguous memory, this allows implementing zero-copying
+use-cases.
+
+Note, while using this scenario the following should be considered:
+
+#. If guest domain dies then pages/grants received from the backend
+   cannot be claimed back
+
+#. Misbehaving guest may send too many requests to the
+   backend exhausting its grant references and memory
+   (consider this from security POV).
+
+Driver limitations
+==================
+
+#. Only primary plane without additional properties is supported.
+
+#. Only one video mode per connector supported which is configured via XenStore.
+
+#. All CRTCs operate at fixed frequency of 60Hz.
-- 
2.7.4