[v6] unstable/drm-lease: DRM lease protocol support

Submitted by Drew DeVault on July 30, 2019, 12:53 p.m.

Details

Message ID 20190730125331.22641-1-sir@cmpwn.com
State New
Headers show
Series "unstable/drm-lease: DRM lease protocol support" ( rev: 6 ) in Wayland

Not browsing as part of any series.

Commit Message

Drew DeVault July 30, 2019, 12:53 p.m.
From: Marius Vlad <marius.vlad@collabora.com>

DRM leasing is a feature which allows the DRM master to "lease" a subset
of its DRM resources to another DRM master via drmModeCreateLease, which
returns a file descriptor for the new DRM master. We use this protocol
to negotiate the terms of the lease and transfer this file descriptor to
clients.

In less DRM-specific terms: this protocol allows Wayland compositors to
give over their GPU resources (like displays) to a Wayland client to
exclusively control.

The primary use-case for this is Virtual Reality headsets, which via the
non-desktop DRM property are generally not used as desktop displays by
Wayland compositors, and for latency reasons (among others) are most
useful to games et al if they have direct control over the DRM resources
associated with it. Basically, these are peripherals which are of no use
to the compositor and may be of use to a client, but since they are tied
up in DRM we need to use DRM leasing to get them into client's hands.

Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
Signed-off-by: Drew DeVault <sir@cmpwn.com>
---
When implementing this for Xwayland, we realized that we would really
like to be able to obtain a lease with zero connectors. The kernel does
not support this today, but adding support shouldn't be especially
difficult. v6 changes the protocol accordingly to allow for leases with
zero connectors, though on today's kernels this will fail vaugely with
the finished event.

 Makefile.am                                  |   1 +
 unstable/drm-lease/README                    |   5 +
 unstable/drm-lease/drm-lease-unstable-v1.xml | 246 +++++++++++++++++++
 3 files changed, 252 insertions(+)
 create mode 100644 unstable/drm-lease/README
 create mode 100644 unstable/drm-lease/drm-lease-unstable-v1.xml

Patch hide | download patch | download mbox

diff --git a/Makefile.am b/Makefile.am
index 345ae6a..d9fff89 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -4,6 +4,7 @@  unstable_protocols =								\
 	unstable/pointer-gestures/pointer-gestures-unstable-v1.xml		\
 	unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml		\
 	unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml			\
+	unstable/drm-lease/drm-lease-unstable-v1.xml				\
 	unstable/text-input/text-input-unstable-v1.xml				\
 	unstable/text-input/text-input-unstable-v3.xml				\
 	unstable/input-method/input-method-unstable-v1.xml			\
diff --git a/unstable/drm-lease/README b/unstable/drm-lease/README
new file mode 100644
index 0000000..16f8551
--- /dev/null
+++ b/unstable/drm-lease/README
@@ -0,0 +1,5 @@ 
+Linux DRM lease
+
+Maintainers:
+Drew DeVault <sir@cmpwn.com>
+Marius Vlad <marius-cristian.vlad@nxp.com>
diff --git a/unstable/drm-lease/drm-lease-unstable-v1.xml b/unstable/drm-lease/drm-lease-unstable-v1.xml
new file mode 100644
index 0000000..083d004
--- /dev/null
+++ b/unstable/drm-lease/drm-lease-unstable-v1.xml
@@ -0,0 +1,246 @@ 
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="drm_lease_unstable_v1">
+  <copyright>
+    Copyright © 2018 NXP
+    Copyright © 2019 Status Research &amp; Development GmbH.
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <interface name="zwp_drm_lease_manager_v1" version="1">
+    <description summary="lease manager">
+      This protocol is used by Wayland compositors which act as Direct
+      Renderering Manager (DRM) masters to lease DRM resources to Wayland
+      clients. Once leased, the compositor will not use the leased resources
+      until the lease is revoked or the client closes the file descriptor.
+
+      The lease manager is used to advertise connectors which are available for
+      leasing, and by the client to negotiate a lease request.
+
+      Warning! The protocol described in this file is experimental and
+      backward incompatible changes may be made. Backward compatible changes
+      may be added together with the corresponding interface version bump.
+      Backward incompatible changes are done by bumping the version number in
+      the protocol and interface names and resetting the interface version.
+      Once the protocol is to be declared stable, the 'z' prefix and the
+      version number in the protocol and interface names are removed and the
+      interface version number is reset.
+    </description>
+
+    <enum name="error">
+      <entry name="stopped_manager" value="0"
+        summary="request sent to a manager which has been stopped"/>
+    </enum>
+
+    <request name="create_lease_request">
+      <description summary="create a lease request object">
+        Creates a lease request object.
+
+        See the documentation for zwp_drm_lease_request_v1 for details.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_drm_lease_request_v1" />
+    </request>
+
+    <request name="stop">
+      <description summary="stop sending events">
+        Indicates the client no longer wishes to receive connector events. The
+        compositor may still send connector events until it sends the finish
+        event, however.
+
+        The client must not send any requests after this one.
+      </description>
+    </request>
+
+    <event name="connector">
+      <description summary="advertise connectors available for leases">
+        The compositor may choose to advertise 0 or more connectors which may be
+        leased to clients, and will use this event to do so. This object may be
+        passed into a lease request to lease that connector. See
+        zwp_drm_lease_request_v1.add_connector for details.
+
+        When this global is bound, the compositor will send all connectors
+        available for lease, but may send additional connectors at any time.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_drm_lease_connector_v1" />
+    </event>
+
+    <event name="finished">
+      <description summary="the compositor has finished using the manager">
+        This event indicates that the compositor is done sending connector
+        events. The compositor will destroy this object immediately after
+        sending this event, and it will become invalid. The client should
+        release any resources associated with this manager after receiving this
+        event.
+      </description>
+    </event>
+  </interface>
+
+  <interface name="zwp_drm_lease_connector_v1" version="1">
+    <description summary="a leasable DRM connector">
+      Represents a DRM connector which is available for lease. These objects are
+      created via zwp_drm_lease_manager_v1.connector, and should be passed into
+      lease requests via zwp_drm_lease_request_v1.add_connector.
+    </description>
+
+    <event name="name">
+      <description summary="name">
+        The compositor sends this event once the connector is created to
+        indicate the name of this connector. This will not change for the
+        duration of the Wayland session, but is not guaranteed to be consistent
+        between sessions.
+
+        If the compositor also supports zxdg_output_manager_v1 and this
+        connector corresponds to a zxdg_output_v1, this name will match the
+        name of this zxdg_output_v1 object.
+      </description>
+      <arg name="name" type="string" summary="connector name" />
+    </event>
+
+    <event name="description">
+      <description summary="description">
+        The compositor sends this event once the connector is created to provide
+        a human-readable description for this connector, which may be presented
+        to the user.
+      </description>
+      <arg name="description" type="string" summary="connector description" />
+    </event>
+
+    <event name="connector_id">
+      <description summary="connector_id">
+        The compositor will send this event to indicate the DRM ID which
+        represents the underlying connector which is being offered. Note that
+        the final lease may include additional object IDs, such as CRTCs and
+        planes.
+      </description>
+      <arg name="connector_id" type="int" summary="DRM Connector ID" />
+    </event>
+
+    <event name="edid">
+      <description summary="edid">
+        The compositor may send this event once the connector is created to
+        provide a file descriptor which may be memory-mapped to read the
+        connector's EDID, to assist in selecting the correct connectors
+        for lease. The fd must be mapped with MAP_PRIVATE by the recipient.
+
+        Note that not all displays have an EDID, and this event will not be
+        sent in such cases.
+      </description>
+      <arg name="edid" type="fd" summary="EDID file descriptor" />
+      <arg name="size" type="uint" summary="EDID size, in bytes"/>
+    </event>
+
+    <event name="withdrawn">
+      <description summary="lease offer withdrawn">
+        Sent to indicate that the compositor will no longer honor requests for
+        DRM leases which include this connector. The client may still issue a
+        lease request including this connector, but the compositor will send
+        zwp_drm_lease_v1.finished without issuing a lease fd.
+      </description>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy connector">
+        The client may send this request to indicate that it will not issue a
+        lease request for this connector. Clients are encouraged to send this
+        after receiving the "withdrawn" request so that the server can release
+        the resources associated with this connector offer.
+      </description>
+    </request>
+  </interface>
+
+  <interface name="zwp_drm_lease_request_v1" version="1">
+    <description summary="DRM lease request">
+      A client that wishes to lease DRM resources will attach the list of
+      connectors advertised with zwp_drm_lease_manager_v1.connector that they
+      wish to lease, then use zwp_drm_lease_request_v1.submit to submit the
+      request.
+    </description>
+
+    <enum name="error">
+      <entry name="submitted_lease" value="0"
+        summary="attempted to reuse a submitted lease"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroys the lease request object">
+        Indicates that the client will no longer use this lease request.
+      </description>
+    </request>
+
+    <request name="request_connector">
+       <description summary="request a connector for this lease">
+         Indicates that the client would like to lease the given connector.
+         This is only used as a suggestion, the compositor may choose to
+         include any resources in the lease it issues, or change the set of
+         leased resources at any time.
+       </description>
+       <arg name="connector" type="object"
+         interface="zwp_drm_lease_connector_v1" />
+    </request>
+
+    <request name="submit">
+       <description summary="submit the lease request">
+         Submits the lease request and creates a new zwp_drm_lease_v1 object.
+         After calling submit, issuing any other request than destroy is a
+         protocol error.
+       </description>
+       <arg name="id" type="new_id" interface="zwp_drm_lease_v1" />
+    </request>
+  </interface>
+
+  <interface name="zwp_drm_lease_v1" version="1">
+    <description summary="a DRM lease">
+      A DRM lease object is used to transfer the DRM file descriptor to the
+      client and manage the lifetime of the lease.
+    </description>
+
+    <event name="lease_fd">
+      <description summary="shares the DRM file descriptor">
+        This event returns a file descriptor suitable for use with DRM-related
+        ioctls. The client should use drmModeGetLease to enumerate the DRM
+        objects which have been leased to them. If the compositor cannot or
+        will not grant a lease for the requested connectors, it will not send
+        this event, instead sending the finished event immediately.
+
+        It is a protocol error for the compositor to send this event more than
+        once for a given lease.
+      </description>
+      <arg name="leased_fd" type="fd" summary="leased DRM file descriptor" />
+    </event>
+
+    <event name="finished">
+      <description summary="sent when the lease has been revoked">
+        When the compositor revokes the lease, it will issue this event to
+        notify clients of the change. If the client requires a new lease, they
+        should destroy this object and submit a new lease request. The
+        compositor will send no further events for this object after sending
+        the finish event.
+      </description>
+    </event>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroys the lease object">
+        The client should send this to indicate that it no longer wishes to use
+        this lease. The compositor should use drmModeRevokeLease on the
+        appropriate file descriptor, if necessary, then release this object.
+      </description>
+    </request>
+  </interface>
+</protocol>

Comments

Xwayland patch based on this work:

https://gitlab.freedesktop.org/xorg/xserver/merge_requests/248

On 2019-07-30 14:53, Drew DeVault wrote:
> From: Marius Vlad <marius.vlad@collabora.com>
> 
> DRM leasing is a feature which allows the DRM master to "lease" a 
> subset
> of its DRM resources to another DRM master via drmModeCreateLease, 
> which
> returns a file descriptor for the new DRM master. We use this protocol
> to negotiate the terms of the lease and transfer this file descriptor 
> to
> clients.
> 
> In less DRM-specific terms: this protocol allows Wayland compositors to
> give over their GPU resources (like displays) to a Wayland client to
> exclusively control.
> 
> The primary use-case for this is Virtual Reality headsets, which via 
> the
> non-desktop DRM property are generally not used as desktop displays by
> Wayland compositors, and for latency reasons (among others) are most
> useful to games et al if they have direct control over the DRM 
> resources
> associated with it. Basically, these are peripherals which are of no 
> use
> to the compositor and may be of use to a client, but since they are 
> tied
> up in DRM we need to use DRM leasing to get them into client's hands.

Talking about use-cases, I'm evaluating leasing for display calibration
and profiling which requires leasing outputs which are are part of the
desktop and also requires user interaction (keyboard, mice). Are there
any ideas on how something like that would work?

I think it would be great if it worked similar to fullscreen surfaces
but input handling depends on having a surface but leasing an output is
independent.

> Signed-off-by: Marius Vlad <marius.vlad@collabora.com>
> Signed-off-by: Drew DeVault <sir@cmpwn.com>
> ---
> When implementing this for Xwayland, we realized that we would really
> like to be able to obtain a lease with zero connectors. The kernel does
> not support this today, but adding support shouldn't be especially
> difficult. v6 changes the protocol accordingly to allow for leases with
> zero connectors, though on today's kernels this will fail vaugely with
> the finished event.
> 
>  Makefile.am                                  |   1 +
>  unstable/drm-lease/README                    |   5 +
>  unstable/drm-lease/drm-lease-unstable-v1.xml | 246 +++++++++++++++++++
>  3 files changed, 252 insertions(+)
>  create mode 100644 unstable/drm-lease/README
>  create mode 100644 unstable/drm-lease/drm-lease-unstable-v1.xml
> 
> diff --git a/Makefile.am b/Makefile.am
> index 345ae6a..d9fff89 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -4,6 +4,7 @@ unstable_protocols =								\
>  	unstable/pointer-gestures/pointer-gestures-unstable-v1.xml		\
>  	unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml		\
>  	unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml			\
> +	unstable/drm-lease/drm-lease-unstable-v1.xml				\
>  	unstable/text-input/text-input-unstable-v1.xml				\
>  	unstable/text-input/text-input-unstable-v3.xml				\
>  	unstable/input-method/input-method-unstable-v1.xml			\
> diff --git a/unstable/drm-lease/README b/unstable/drm-lease/README
> new file mode 100644
> index 0000000..16f8551
> --- /dev/null
> +++ b/unstable/drm-lease/README
> @@ -0,0 +1,5 @@
> +Linux DRM lease
> +
> +Maintainers:
> +Drew DeVault <sir@cmpwn.com>
> +Marius Vlad <marius-cristian.vlad@nxp.com>
> diff --git a/unstable/drm-lease/drm-lease-unstable-v1.xml
> b/unstable/drm-lease/drm-lease-unstable-v1.xml
> new file mode 100644
> index 0000000..083d004
> --- /dev/null
> +++ b/unstable/drm-lease/drm-lease-unstable-v1.xml
> @@ -0,0 +1,246 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="drm_lease_unstable_v1">
> +  <copyright>
> +    Copyright © 2018 NXP
> +    Copyright © 2019 Status Research &amp; Development GmbH.
> +
> +    Permission is hereby granted, free of charge, to any person 
> obtaining a
> +    copy of this software and associated documentation files (the 
> "Software"),
> +    to deal in the Software without restriction, including without 
> limitation
> +    the rights to use, copy, modify, merge, publish, distribute, 
> sublicense,
> +    and/or sell copies of the Software, and to permit persons to whom 
> the
> +    Software is furnished to do so, subject to the following 
> conditions:
> +
> +    The above copyright notice and this permission notice (including 
> the next
> +    paragraph) shall be included in all copies or substantial portions 
> of the
> +    Software.
> +
> +    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
> EXPRESS OR
> +    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 
> MERCHANTABILITY,
> +    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT 
> SHALL
> +    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES 
> OR OTHER
> +    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
> ARISING
> +    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 
> OTHER
> +    DEALINGS IN THE SOFTWARE.
> +  </copyright>
> +
> +  <interface name="zwp_drm_lease_manager_v1" version="1">
> +    <description summary="lease manager">
> +      This protocol is used by Wayland compositors which act as Direct
> +      Renderering Manager (DRM) masters to lease DRM resources to 
> Wayland
> +      clients. Once leased, the compositor will not use the leased 
> resources
> +      until the lease is revoked or the client closes the file 
> descriptor.
> +
> +      The lease manager is used to advertise connectors which are 
> available for
> +      leasing, and by the client to negotiate a lease request.
> +
> +      Warning! The protocol described in this file is experimental and
> +      backward incompatible changes may be made. Backward compatible 
> changes
> +      may be added together with the corresponding interface version 
> bump.
> +      Backward incompatible changes are done by bumping the version 
> number in
> +      the protocol and interface names and resetting the interface 
> version.
> +      Once the protocol is to be declared stable, the 'z' prefix and 
> the
> +      version number in the protocol and interface names are removed 
> and the
> +      interface version number is reset.
> +    </description>
> +
> +    <enum name="error">
> +      <entry name="stopped_manager" value="0"
> +        summary="request sent to a manager which has been stopped"/>
> +    </enum>
> +
> +    <request name="create_lease_request">
> +      <description summary="create a lease request object">
> +        Creates a lease request object.
> +
> +        See the documentation for zwp_drm_lease_request_v1 for 
> details.
> +      </description>
> +      <arg name="id" type="new_id" 
> interface="zwp_drm_lease_request_v1" />
> +    </request>
> +
> +    <request name="stop">
> +      <description summary="stop sending events">
> +        Indicates the client no longer wishes to receive connector 
> events. The
> +        compositor may still send connector events until it sends the 
> finish
> +        event, however.
> +
> +        The client must not send any requests after this one.
> +      </description>
> +    </request>
> +
> +    <event name="connector">
> +      <description summary="advertise connectors available for 
> leases">
> +        The compositor may choose to advertise 0 or more connectors
> which may be
> +        leased to clients, and will use this event to do so. This 
> object may be
> +        passed into a lease request to lease that connector. See
> +        zwp_drm_lease_request_v1.add_connector for details.
> +
> +        When this global is bound, the compositor will send all 
> connectors
> +        available for lease, but may send additional connectors at any 
> time.
> +      </description>
> +      <arg name="id" type="new_id" 
> interface="zwp_drm_lease_connector_v1" />
> +    </event>
> +
> +    <event name="finished">
> +      <description summary="the compositor has finished using the 
> manager">
> +        This event indicates that the compositor is done sending 
> connector
> +        events. The compositor will destroy this object immediately 
> after
> +        sending this event, and it will become invalid. The client 
> should
> +        release any resources associated with this manager after 
> receiving this
> +        event.
> +      </description>
> +    </event>
> +  </interface>
> +
> +  <interface name="zwp_drm_lease_connector_v1" version="1">
> +    <description summary="a leasable DRM connector">
> +      Represents a DRM connector which is available for lease. These
> objects are
> +      created via zwp_drm_lease_manager_v1.connector, and should be 
> passed into
> +      lease requests via zwp_drm_lease_request_v1.add_connector.
> +    </description>
> +
> +    <event name="name">
> +      <description summary="name">
> +        The compositor sends this event once the connector is created 
> to
> +        indicate the name of this connector. This will not change for 
> the
> +        duration of the Wayland session, but is not guaranteed to be 
> consistent
> +        between sessions.
> +
> +        If the compositor also supports zxdg_output_manager_v1 and 
> this
> +        connector corresponds to a zxdg_output_v1, this name will 
> match the
> +        name of this zxdg_output_v1 object.
> +      </description>
> +      <arg name="name" type="string" summary="connector name" />
> +    </event>
> +
> +    <event name="description">
> +      <description summary="description">
> +        The compositor sends this event once the connector is created
> to provide
> +        a human-readable description for this connector, which may be 
> presented
> +        to the user.
> +      </description>
> +      <arg name="description" type="string" summary="connector 
> description" />
> +    </event>
> +
> +    <event name="connector_id">
> +      <description summary="connector_id">
> +        The compositor will send this event to indicate the DRM ID 
> which
> +        represents the underlying connector which is being offered. 
> Note that
> +        the final lease may include additional object IDs, such as 
> CRTCs and
> +        planes.
> +      </description>
> +      <arg name="connector_id" type="int" summary="DRM Connector ID" 
> />
> +    </event>
> +
> +    <event name="edid">
> +      <description summary="edid">
> +        The compositor may send this event once the connector is 
> created to
> +        provide a file descriptor which may be memory-mapped to read 
> the
> +        connector's EDID, to assist in selecting the correct 
> connectors
> +        for lease. The fd must be mapped with MAP_PRIVATE by the 
> recipient.
> +
> +        Note that not all displays have an EDID, and this event will 
> not be
> +        sent in such cases.
> +      </description>
> +      <arg name="edid" type="fd" summary="EDID file descriptor" />
> +      <arg name="size" type="uint" summary="EDID size, in bytes"/>
> +    </event>
> +
> +    <event name="withdrawn">
> +      <description summary="lease offer withdrawn">
> +        Sent to indicate that the compositor will no longer honor 
> requests for
> +        DRM leases which include this connector. The client may still 
> issue a
> +        lease request including this connector, but the compositor 
> will send
> +        zwp_drm_lease_v1.finished without issuing a lease fd.
> +      </description>
> +    </event>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy connector">
> +        The client may send this request to indicate that it will not 
> issue a
> +        lease request for this connector. Clients are encouraged to 
> send this
> +        after receiving the "withdrawn" request so that the server can 
> release
> +        the resources associated with this connector offer.
> +      </description>
> +    </request>
> +  </interface>
> +
> +  <interface name="zwp_drm_lease_request_v1" version="1">
> +    <description summary="DRM lease request">
> +      A client that wishes to lease DRM resources will attach the list 
> of
> +      connectors advertised with zwp_drm_lease_manager_v1.connector 
> that they
> +      wish to lease, then use zwp_drm_lease_request_v1.submit to 
> submit the
> +      request.
> +    </description>
> +
> +    <enum name="error">
> +      <entry name="submitted_lease" value="0"
> +        summary="attempted to reuse a submitted lease"/>
> +    </enum>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroys the lease request object">
> +        Indicates that the client will no longer use this lease 
> request.
> +      </description>
> +    </request>
> +
> +    <request name="request_connector">
> +       <description summary="request a connector for this lease">
> +         Indicates that the client would like to lease the given 
> connector.
> +         This is only used as a suggestion, the compositor may choose 
> to
> +         include any resources in the lease it issues, or change the 
> set of
> +         leased resources at any time.
> +       </description>
> +       <arg name="connector" type="object"
> +         interface="zwp_drm_lease_connector_v1" />
> +    </request>
> +
> +    <request name="submit">
> +       <description summary="submit the lease request">
> +         Submits the lease request and creates a new zwp_drm_lease_v1 
> object.
> +         After calling submit, issuing any other request than destroy 
> is a
> +         protocol error.
> +       </description>
> +       <arg name="id" type="new_id" interface="zwp_drm_lease_v1" />
> +    </request>
> +  </interface>
> +
> +  <interface name="zwp_drm_lease_v1" version="1">
> +    <description summary="a DRM lease">
> +      A DRM lease object is used to transfer the DRM file descriptor 
> to the
> +      client and manage the lifetime of the lease.
> +    </description>
> +
> +    <event name="lease_fd">
> +      <description summary="shares the DRM file descriptor">
> +        This event returns a file descriptor suitable for use with 
> DRM-related
> +        ioctls. The client should use drmModeGetLease to enumerate the 
> DRM
> +        objects which have been leased to them. If the compositor 
> cannot or
> +        will not grant a lease for the requested connectors, it will 
> not send
> +        this event, instead sending the finished event immediately.
> +
> +        It is a protocol error for the compositor to send this event 
> more than
> +        once for a given lease.
> +      </description>
> +      <arg name="leased_fd" type="fd" summary="leased DRM file 
> descriptor" />
> +    </event>
> +
> +    <event name="finished">
> +      <description summary="sent when the lease has been revoked">
> +        When the compositor revokes the lease, it will issue this 
> event to
> +        notify clients of the change. If the client requires a new 
> lease, they
> +        should destroy this object and submit a new lease request. The
> +        compositor will send no further events for this object after 
> sending
> +        the finish event.
> +      </description>
> +    </event>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroys the lease object">
> +        The client should send this to indicate that it no longer 
> wishes to use
> +        this lease. The compositor should use drmModeRevokeLease on 
> the
> +        appropriate file descriptor, if necessary, then release this 
> object.
> +      </description>
> +    </request>
> +  </interface>
> +</protocol>
On Tuesday, September 3, 2019 1:15 AM, Sebastian Wick <sebastian@sebastianwick.net> wrote:

> On 2019-07-30 14:53, Drew DeVault wrote:
>
> > From: Marius Vlad marius.vlad@collabora.com
> > DRM leasing is a feature which allows the DRM master to "lease" a
> > subset
> > of its DRM resources to another DRM master via drmModeCreateLease,
> > which
> > returns a file descriptor for the new DRM master. We use this protocol
> > to negotiate the terms of the lease and transfer this file descriptor
> > to
> > clients.
> > In less DRM-specific terms: this protocol allows Wayland compositors to
> > give over their GPU resources (like displays) to a Wayland client to
> > exclusively control.
> > The primary use-case for this is Virtual Reality headsets, which via
> > the
> > non-desktop DRM property are generally not used as desktop displays by
> > Wayland compositors, and for latency reasons (among others) are most
> > useful to games et al if they have direct control over the DRM
> > resources
> > associated with it. Basically, these are peripherals which are of no
> > use
> > to the compositor and may be of use to a client, but since they are
> > tied
> > up in DRM we need to use DRM leasing to get them into client's hands.
>
> Talking about use-cases, I'm evaluating leasing for display calibration
> and profiling which requires leasing outputs which are are part of the
> desktop and also requires user interaction (keyboard, mice). Are there
> any ideas on how something like that would work?
>
> I think it would be great if it worked similar to fullscreen surfaces
> but input handling depends on having a surface but leasing an output is
> independent.

I'd rather not use DRM leasing for this. See the earlier discussions
about DRM leasing use-cases.

On Mon Sep 2, 2019 at 3:51 PM Pekka Paalanen wrote:
> Hi Drew,
> 
> I seem to recall that you didn't want to add multi-DRM-device support
> here just yet and go first with just one implied DRM device. That is
> ok, but would be nice to have a TODO note somewhere near the top in the
> XML file saying that this will be re-designed to support multiple DRM
> devices at some point.

This was resolved by choosing to have multiple drm_lease_manager
globals, one for each DRM device. No reworking should be necessary.

> Can you point to the discussion or elaborate here on when a zero
> connector lease would be useful?
> 
> I checked the Xwayland discussion and didn't see it there. I remember
> some old talk about giving out a no-resources lease first for
> discovering DRM resources to lease, but that didn't work because
> non-leased resources would not be visible either.

https://gitlab.freedesktop.org/xorg/xserver/issues/864

The main issue is that we have no way to enumerate detailed mode
information in Xwayland to populate RandR, which is used by X clients in
the wild today to prep for a DRM lease (the corresponding X extension
for Vulkan is an example of where this is a problem).

On Thu Sep 12, 2019 at 2:42 PM Pekka Paalanen wrote:
> > This was resolved by choosing to have multiple drm_lease_manager
> > globals, one for each DRM device. No reworking should be necessary.
> 
> in that case, document it in the XML please.

ack

> > The main issue is that we have no way to enumerate detailed mode
> > information in Xwayland to populate RandR, which is used by X clients in
> > the wild today to prep for a DRM lease (the corresponding X extension
> > for Vulkan is an example of where this is a problem).
> 
> Oh yes, that.
> 
> If that is to be solved with Wayland protocol, you'd have to send
> events with all the kernel video modes.

I thought about this, but I don't really like it. It would be adding
more complexity to this protocol for the sake of propping up a
second-class implementation, namely Xwayland. In the future, the
EDID/name/description should be more than sufficient to select the
hardware you want to lease, and from that point forward you should just
query DRM yourself to find modes and such. One source of truth is better
than two.

> Was it considered to give out full (as in, not leased) but non-master
> DRM device fds for iterating possible resources? A compositor would get
> one by opening the DRM device again. I'm assuming that logind would do
> a new open() for it.

Some care would have to be taken to make sure that the compositor
creates a non-master DRM fd instead of accidentally making another
master fd. I think this would be a reasonable solution, though.

> I'm starting to think that what you might need is a lease fd that
> cannot be DRM-master. Then the compositor could create a "pre-lease"
> with all the resources it could be willing to lease out. The client
> would use KMS UAPI to query everything, and then decide what it wants to
> actually lease. That would avoid sending EDID, modes and whatnot over
> Wayland.

Or, simplifying things, we could send them that non-master fd and then
they can just query it themselves and match the resources by their IDs
with the resources offered for lease by the compositor. I'm not sure why
constraining the resources they can browse (read-only) is necessary. We
could drop the EDID if we went with this approach.

> I might favour sysfs, but then I guess BSD would be left out cold.

NACK to sysfs for this reason
On Fri, Sep 13, 2019 at 09:32:01AM -0400, Drew DeVault wrote:
> On Thu Sep 12, 2019 at 2:42 PM Pekka Paalanen wrote:
> > > This was resolved by choosing to have multiple drm_lease_manager
> > > globals, one for each DRM device. No reworking should be necessary.
> > 
> > in that case, document it in the XML please.
> 
> ack
> 

If one global corresponds to a single drm device, why not call it
"_device" instead of "_manager"? Usually there is only one "manager"
object, and it'd be confusing to have multiple manager objects without
it being clear that it's per device.

Being globals it's prone to race conditions as well (I'd expect to see
leasable devices to come and go, especially with eGPU's being a thing).
Then again, with wl_global_remove() it's not *that* bad.

The alternative is to make the _manager object an actual manager object
that has 'added' and 'removed' events with the "_device" containing the
actual lease request.


Jonas

On Mon Sep 16, 2019 at 11:57 AM Pekka Paalanen wrote:
> > Or, simplifying things, we could send them that non-master fd and then
> > they can just query it themselves and match the resources by their IDs
> > with the resources offered for lease by the compositor. I'm not sure why
> > constraining the resources they can browse (read-only) is necessary. We
> > could drop the EDID if we went with this approach.
> 
> My only reason is that it would be obvious which resources the
> compositor will not lease out. If the resource picking in the client is
> automatic, that's not a big deal. But if the client has some UI to let
> the user pick a connector, it might be useful. Or, we need accompanying
> Wayland events to carry the leasability, but they could be as simple as
> device/drm-resource-id and nothing more.

I think for this to work we'd want to keep the event which shares the
object IDs available for lease.