From mboxrd@z Thu Jan 1 00:00:00 1970 From: Oleksandr Andrushchenko 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> References: <1520958066-22875-1-git-send-email-andr2000@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: Received: from mail-lf0-x243.google.com (mail-lf0-x243.google.com [IPv6:2a00:1450:4010:c07::243]) by gabe.freedesktop.org (Postfix) with ESMTPS id 395316E564 for ; Tue, 13 Mar 2018 16:21:24 +0000 (UTC) Received: by mail-lf0-x243.google.com with SMTP id p74-v6so282208lfd.3 for ; Tue, 13 Mar 2018 09:21:23 -0700 (PDT) In-Reply-To: <1520958066-22875-1-git-send-email-andr2000@gmail.com> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" 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 List-Id: dri-devel@lists.freedesktop.org RnJvbTogT2xla3NhbmRyIEFuZHJ1c2hjaGVua28gPG9sZWtzYW5kcl9hbmRydXNoY2hlbmtvQGVw YW0uY29tPgoKUHJvdmlkZSBrZXJuZWwgZG9jdW1lbnRhdGlvbiBmb3IgdGhlIFhlbiBwYXJhLXZp cnR1YWxpemVkCmZyb250ZW5kIERSTSBkcml2ZXIuCgpTaWduZWQtb2ZmLWJ5OiBPbGVrc2FuZHIg QW5kcnVzaGNoZW5rbyA8b2xla3NhbmRyX2FuZHJ1c2hjaGVua29AZXBhbS5jb20+Ci0tLQogRG9j dW1lbnRhdGlvbi9ncHUvaW5kZXgucnN0ICAgICB8ICAxICsKIERvY3VtZW50YXRpb24vZ3B1L3hl bi1mcm9udC5yc3QgfCA3NyArKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysr KwogMiBmaWxlcyBjaGFuZ2VkLCA3OCBpbnNlcnRpb25zKCspCiBjcmVhdGUgbW9kZSAxMDA2NDQg RG9jdW1lbnRhdGlvbi9ncHUveGVuLWZyb250LnJzdAoKZGlmZiAtLWdpdCBhL0RvY3VtZW50YXRp b24vZ3B1L2luZGV4LnJzdCBiL0RvY3VtZW50YXRpb24vZ3B1L2luZGV4LnJzdAppbmRleCBjMzY1 ODZkYWQyOWQuLmUzMTY4NGFmMGEyMCAxMDA2NDQKLS0tIGEvRG9jdW1lbnRhdGlvbi9ncHUvaW5k ZXgucnN0CisrKyBiL0RvY3VtZW50YXRpb24vZ3B1L2luZGV4LnJzdApAQCAtMjAsNiArMjAsNyBA QCBMaW51eCBHUFUgRHJpdmVyIERldmVsb3BlcidzIEd1aWRlCiAgICB2Z2Etc3dpdGNoZXJvbwog ICAgdmdhYXJiaXRlcgogICAgYnJpZGdlL2R3LWhkbWkKKyAgIHhlbi1mcm9udAogICAgdG9kbwog CiAuLiBvbmx5OjogIHN1YnByb2plY3QgYW5kIGh0bWwKZGlmZiAtLWdpdCBhL0RvY3VtZW50YXRp b24vZ3B1L3hlbi1mcm9udC5yc3QgYi9Eb2N1bWVudGF0aW9uL2dwdS94ZW4tZnJvbnQucnN0Cm5l dyBmaWxlIG1vZGUgMTAwNjQ0CmluZGV4IDAwMDAwMDAwMDAwMC4uNmFjMGI3NTM3M2M0Ci0tLSAv ZGV2L251bGwKKysrIGIvRG9jdW1lbnRhdGlvbi9ncHUveGVuLWZyb250LnJzdApAQCAtMCwwICsx LDc3IEBACis9PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT0KK1hlbiBwYXJhLXZp cnR1YWxpemVkIGZyb250ZW5kIGRyaXZlcgorPT09PT09PT09PT09PT09PT09PT09PT09PT09PT09 PT09PT09CitUaGlzIGZyb250ZW5kIGRyaXZlciBpbXBsZW1lbnRzIFhlbiBwYXJhLXZpcnR1YWxp emVkIGRpc3BsYXkKK2FjY29yZGluZyB0byB0aGUgZGlzcGxheSBwcm90b2NvbCBkZXNjcmliZWQg YXQKK2luY2x1ZGUveGVuL2ludGVyZmFjZS9pby9kaXNwbGlmLmgKKworRHJpdmVyIG1vZGVzIG9m IG9wZXJhdGlvbiBpbiB0ZXJtcyBvZiBkaXNwbGF5IGJ1ZmZlcnMgdXNlZAorPT09PT09PT09PT09 PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PT09PQorCitEZXBlbmRp bmcgb24gdGhlIHJlcXVpcmVtZW50cyBmb3IgdGhlIHBhcmEtdmlydHVhbGl6ZWQgZW52aXJvbm1l bnQsIG5hbWVseQorcmVxdWlyZW1lbnRzIGRpY3RhdGVkIGJ5IHRoZSBhY2NvbXBhbnlpbmcgRFJN Lyh2KUdQVSBkcml2ZXJzIHJ1bm5pbmcgaW4gYm90aAoraG9zdCBhbmQgZ3Vlc3QgZW52aXJvbm1l bnRzLCBudW1iZXIgb2Ygb3BlcmF0aW5nIG1vZGVzIG9mIHBhcmEtdmlydHVhbGl6ZWQKK2Rpc3Bs YXkgZHJpdmVyIGFyZSBzdXBwb3J0ZWQ6CisKKy0gZGlzcGxheSBidWZmZXJzIGNhbiBiZSBhbGxv Y2F0ZWQgYnkgZWl0aGVyIGZyb250ZW5kIGRyaXZlciBvciBiYWNrZW5kCistIGRpc3BsYXkgYnVm ZmVycyBjYW4gYmUgYWxsb2NhdGVkIHRvIGJlIGNvbnRpZ3VvdXMgaW4gbWVtb3J5IG9yIG5vdAor CitOb3RlISBGcm9udGVuZCBkcml2ZXIgaXRzZWxmIGhhcyBubyBkZXBlbmRlbmN5IG9uIGNvbnRp Z3VvdXMgbWVtb3J5IGZvcgoraXRzIG9wZXJhdGlvbi4KKworQnVmZmVycyBhbGxvY2F0ZWQgYnkg dGhlIGZyb250ZW5kIGRyaXZlcgorLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0t LS0tLQorCitUaGUgYmVsb3cgbW9kZXMgb2Ygb3BlcmF0aW9uIGFyZSBjb25maWd1cmVkIGF0IGNv bXBpbGUtdGltZSB2aWEKK2Zyb250ZW5kIGRyaXZlcidzIGtlcm5lbCBjb25maWd1cmF0aW9uOgor CitXaXRoIEdFTSBDTUEgaGVscGVycworfn5+fn5+fn5+fn5+fn5+fn5+fn4KKyBUaGlzIHVzZS1j YXNlIGlzIHVzZWZ1bCB3aGVuIHVzZWQgd2l0aCBhY2NvbXBhbnlpbmcgRFJNL3ZHUFUgZHJpdmVy IGluCisgZ3Vlc3QgZG9tYWluIHdoaWNoIHdhcyBkZXNpZ25lZCB0byBvbmx5IHdvcmsgd2l0aCBj b250aWd1b3VzIGJ1ZmZlcnMsCisgZS5nLiBEUk0gZHJpdmVyIGJhc2VkIG9uIEdFTSBDTUEgaGVs cGVyczogc3VjaCBkcml2ZXJzIGNhbiBvbmx5IGltcG9ydAorIGNvbnRpZ3VvdXMgUFJJTUUgYnVm ZmVycywgdGh1cyByZXF1aXJpbmcgZnJvbnRlbmQgZHJpdmVyIHRvIHByb3ZpZGUKKyBzdWNoLiBJ biBvcmRlciB0byBpbXBsZW1lbnQgdGhpcyBtb2RlIG9mIG9wZXJhdGlvbiBwYXJhLXZpcnR1YWxp emVkCisgZnJvbnRlbmQgZHJpdmVyIGNhbiBiZSBjb25maWd1cmVkIHRvIHVzZSBHRU0gQ01BIGhl bHBlcnMuCisKK1dpdGhvdXQgR0VNIENNQSBoZWxwZXJzCit+fn5+fn5+fn5+fn5+fn5+fn5+fn5+ fgorIElmIGFjY29tcGFueWluZyBkcml2ZXJzIGNhbiBjb3BlIHdpdGggbm9uLWNvbnRpZ3VvdXMg bWVtb3J5IHRoZW4sIHRvCisgbG93ZXIgcHJlc3N1cmUgb24gQ01BIHN1YnN5c3RlbSBvZiB0aGUg a2VybmVsLCBkcml2ZXIgY2FuIGFsbG9jYXRlCisgYnVmZmVycyBmcm9tIHN5c3RlbSBtZW1vcnku CisKKyBOb3RlISBJZiB1c2VkIHdpdGggYWNjb21wYW55aW5nIERSTS8odilHUFUgZHJpdmVycyB0 aGlzIG1vZGUgb2Ygb3BlcmF0aW9uCisgbWF5IHJlcXVpcmUgSU9NTVUgc3VwcG9ydCBvbiB0aGUg cGxhdGZvcm0sIHNvIGFjY29tcGFueWluZyBEUk0vdkdQVQorIGhhcmR3YXJlIGNhbiBzdGlsbCBy ZWFjaCBkaXNwbGF5IGJ1ZmZlciBtZW1vcnkgd2hpbGUgaW1wb3J0aW5nIFBSSU1FCisgYnVmZmVy cyBmcm9tIHRoZSBmcm9udGVuZCBkcml2ZXIuCisKK0J1ZmZlcnMgYWxsb2NhdGVkIGJ5IHRoZSBi YWNrZW5kCistLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLQorCitUaGlzIG1vZGUgb2Yg b3BlcmF0aW9uIGlzIHJ1bi10aW1lIGNvbmZpZ3VyZWQgdmlhIGd1ZXN0IGRvbWFpbiBjb25maWd1 cmF0aW9uCit0aHJvdWdoIFhlblN0b3JlIGVudHJpZXMuCisKK0ZvciBzeXN0ZW1zIHdoaWNoIGRv IG5vdCBwcm92aWRlIElPTU1VIHN1cHBvcnQsIGJ1dCBoYXZpbmcgc3BlY2lmaWMKK3JlcXVpcmVt ZW50cyBmb3IgZGlzcGxheSBidWZmZXJzIGl0IGlzIHBvc3NpYmxlIHRvIGFsbG9jYXRlIHN1Y2gg YnVmZmVycworYXQgYmFja2VuZCBzaWRlIGFuZCBzaGFyZSB0aG9zZSB3aXRoIHRoZSBmcm9udGVu ZC4KK0ZvciBleGFtcGxlLCBpZiBob3N0IGRvbWFpbiBpcyAxOjEgbWFwcGVkIGFuZCBoYXMgRFJN L0dQVSBoYXJkd2FyZSBleHBlY3RpbmcKK3BoeXNpY2FsbHkgY29udGlndW91cyBtZW1vcnksIHRo aXMgYWxsb3dzIGltcGxlbWVudGluZyB6ZXJvLWNvcHlpbmcKK3VzZS1jYXNlcy4KKworTm90ZSwg d2hpbGUgdXNpbmcgdGhpcyBzY2VuYXJpbyB0aGUgZm9sbG93aW5nIHNob3VsZCBiZSBjb25zaWRl cmVkOgorCisjLiBJZiBndWVzdCBkb21haW4gZGllcyB0aGVuIHBhZ2VzL2dyYW50cyByZWNlaXZl ZCBmcm9tIHRoZSBiYWNrZW5kCisgICBjYW5ub3QgYmUgY2xhaW1lZCBiYWNrCisKKyMuIE1pc2Jl aGF2aW5nIGd1ZXN0IG1heSBzZW5kIHRvbyBtYW55IHJlcXVlc3RzIHRvIHRoZQorICAgYmFja2Vu ZCBleGhhdXN0aW5nIGl0cyBncmFudCByZWZlcmVuY2VzIGFuZCBtZW1vcnkKKyAgIChjb25zaWRl ciB0aGlzIGZyb20gc2VjdXJpdHkgUE9WKS4KKworRHJpdmVyIGxpbWl0YXRpb25zCis9PT09PT09 PT09PT09PT09PT0KKworIy4gT25seSBwcmltYXJ5IHBsYW5lIHdpdGhvdXQgYWRkaXRpb25hbCBw cm9wZXJ0aWVzIGlzIHN1cHBvcnRlZC4KKworIy4gT25seSBvbmUgdmlkZW8gbW9kZSBwZXIgY29u bmVjdG9yIHN1cHBvcnRlZCB3aGljaCBpcyBjb25maWd1cmVkIHZpYSBYZW5TdG9yZS4KKworIy4g QWxsIENSVENzIG9wZXJhdGUgYXQgZml4ZWQgZnJlcXVlbmN5IG9mIDYwSHouCi0tIAoyLjcuNAoK X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX18KZHJpLWRldmVs IG1haWxpbmcgbGlzdApkcmktZGV2ZWxAbGlzdHMuZnJlZWRlc2t0b3Aub3JnCmh0dHBzOi8vbGlz dHMuZnJlZWRlc2t0b3Aub3JnL21haWxtYW4vbGlzdGluZm8vZHJpLWRldmVsCg== From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S934002AbeCMQV3 (ORCPT ); Tue, 13 Mar 2018 12:21:29 -0400 Received: from mail-lf0-f65.google.com ([209.85.215.65]:43462 "EHLO mail-lf0-f65.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933946AbeCMQVY (ORCPT ); Tue, 13 Mar 2018 12:21:24 -0400 X-Google-Smtp-Source: AG47ELu4w+ejLGTQlv+hvBodVjHZqx3OU+hNUO640mUShkM0rN+aR2IdpNYhBxBfxzWQXsKDOguHZg== From: Oleksandr Andrushchenko 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 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> X-Mailer: git-send-email 2.7.4 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 List-ID: X-Mailing-List: linux-kernel@vger.kernel.org From: Oleksandr Andrushchenko Provide kernel documentation for the Xen para-virtualized frontend DRM driver. Signed-off-by: Oleksandr Andrushchenko --- 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