Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67;
From:   Oleksandr Andrushchenko <andr2000@gmail.com>
To:     xen-devel@lists.xenproject.org, linux-kernel@vger.kernel.org,
        dri-devel@lists.freedesktop.org, airlied@linux.ie,
        daniel.vetter@intel.com, seanpaul@chromium.org,
        gustavo@padovan.org, jgross@suse.com, boris.ostrovsky@oracle.com,
        konrad.wilk@oracle.com
Cc:     andr2000@gmail.com,
        Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>
Subject: [PATCH RESEND v2 2/2] drm/xen-front: Provide kernel documentation
Date:   Tue, 13 Mar 2018 18:21:06 +0200
Message-Id: <1520958066-22875-3-git-send-email-andr2000@gmail.com>
In-Reply-To: <1520958066-22875-1-git-send-email-andr2000@gmail.com>
References: <1520958066-22875-1-git-send-email-andr2000@gmail.com>
Sender: linux-kernel-owner@vger.kernel.org
Precedence: bulk

From: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>

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

Signed-off-by: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>
---
 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