> From: Marius Vlad <marius.v...@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.v...@collabora.com> > Signed-off-by: Drew DeVault <s...@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 <s...@cmpwn.com> > +Marius Vlad <marius-cristian.v...@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@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
