[PATCH v3] unstable/drm-lease: DRM lease protocol support
Simon Ser
contact at emersion.fr
Mon Jul 15 17:46:27 UTC 2019
> From: Marius Vlad <marius.vlad at 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 at collabora.com>
> Signed-off-by: Drew DeVault <sir at cmpwn.com>
> ---
> This version changes the EDID from a wl_array to a file descriptor, to
> account for possibly large EDIDs. I've updated my wlroots and kmscube
> patches accordingly.
>
> I've started working on adding this to Vulkan as well, and a problem
> occured to me: we'll have to immortalize the interface names in a VK
> extension in order to push it upstream, which means that we can't
> upstream a VK extension based on an unstable version of this protocol
> and cleanly upgrade it to the stable version later. I spoke about this
> with Daniel Stone and we think that the best approach is to prepare
> implementations of this protocol in an out-of-tree Mesa fork with an
> unsubmitted Vk extension to prove its suitability, then fast-track this
> protocol from unstable to stable once we reach consensus. Open to
> comment if anyone has a better plan.
>
> Makefile.am | 1 +
> unstable/drm-lease/README | 5 +
> unstable/drm-lease/drm-lease-unstable-v1.xml | 238 +++++++++++++++++++
> 3 files changed, 244 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 at cmpwn.com>
> +Marius Vlad <marius-cristian.vlad at 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..c7e4715
> --- /dev/null
> +++ b/unstable/drm-lease/drm-lease-unstable-v1.xml
> @@ -0,0 +1,238 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="drm_lease_unstable_v1">
> + <copyright>
> + Copyright © 2018 NXP
> + Copyright © 2019 Status Research & 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>
> +
> + <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.
Protocol error?
> + </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.
request_connector? (Maybe add_connector is a better name?)
> + </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. This will not change for the duration of the Wayland
> + session, but is not guaranteed to be consistent between sessions.
There is a pending patch to make xdg_output.description mutable.
> + If the compositor also supports zxdg_output_manager_v1 and this
> + connector corresponds to a zxdg_output_v1, this description will match
> + the description of this zxdg_output_v1 object.
This is probably not strictly necessary, and will make it difficult to honour if
xdg_output.description becomes mutable (both events aren't applied atomically).
> + </description>
> + <arg name="name" type="string" summary="connector name" />
s/name/description/g
> + </event>
> +
> + <event name="edid">
> + <description summary="edid">
> + The compositor sends 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.
Make it necessary to map with MAP_PRIVATE. See [1] for details.
Some connectors may not have an EDID (e.g. old VGA outputs, or when the EDID is
corrupted). Maybe this event should be optional?
[1]: https://gitlab.freedesktop.org/wayland/wayland/commit/905c0a341ddf0a885811d19e2b79c65a3f1d210c
> + </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.
What if multiple connectors have been requested?
Maybe it's safer to say that the compositor won't issue a lease with this
connector.
> + </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="no_connectors" value="0"
> + summary="request submitted with zero connectors"/>
> + <entry name="submitted_lease" value="1"
> + 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. Submitting a lease request with no connectors 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, which may not be the objects
> + they requested. The lease may have zero DRM objects.
Zero objects is not possible IIRC, right?
> + The compositor may also issue and immediately revoke the lease if no
> + connectors are leasable, in which case this event is not sent.
> +
> + 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>
> --
> 2.22.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list