Simple protocol extension to manage DRM lease. Based on the work by Keith Packard in [1], respectively [2].
[1] https://cgit.freedesktop.org/mesa/drm/commit/?id=c4171535389d72e9135c9615cecd07b346fd6d7e [2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?h=v4.15-rc9&id=62884cd386b876638720ef88374b31a84ca7ee5f Changes since v4: - send also information (gratuitously) about the connector once the client has it a zwp_kms_lease_connector_v1 object (Philipp Zabel) - use the destructor of zwp_kms_lease_v1 to revoke the lease, and remove the zwp_kms_lease_request_v1::revoke request, as this will no longer be necessary (Philipp Zabel) - once the client obtains a zwp_kms_lease_v1 object, using the temporary zwp_kms_lease_request_v1 object is no longer necessary so the client can freely call its destructor (Philipp Zabel) - polished the main commentary to reflect these changes and fixed some minor typos (Philipp Zabel) - removed 'revoked' event entirely as it adds complexity without adding too much benefit. Changes since v3: - instead of advertising all leasable connectors at once, advertise each connector for each leasable output. Use an object to represent a leasable connector and provide a request to add that leasable connector when creating the lease (Philipp Zabel) - add two events to handle add_connector request - add some comments in manager interface to explain how the protocol is designed to work Changes since v2: - advertise connectors when creating a lease request object (Pekka Paalanen) - when revoking the lease use the lease object instead of lessee id (Pekka Paalanen) - various grammar/spelling fixes (Pekka Paalanen) Changes since v1: - added manager: advertise lease capability and manage the lease (Daniel Stone) - add request(s) for adding connector/crtc/plane to behave more like dmabuf (Daniel Stone) Signed-off-by: Marius Vlad <marius-cristian.v...@nxp.com> --- An implementation for this version can be found at https://gitlab.freedesktop.org/marius.vlad0/weston/commits/drm-lease-advertise-each-connnector-object-fixes Makefile.am | 1 + unstable/drm-lease/README | 4 + unstable/drm-lease/drm-lease-unstable-v1.xml | 226 +++++++++++++++++++++++++++ 3 files changed, 231 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 6394e26..5d13dca 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..a25600c --- /dev/null +++ b/unstable/drm-lease/README @@ -0,0 +1,4 @@ +Linux DRM lease + +Maintainers: +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..9fcaea5 --- /dev/null +++ b/unstable/drm-lease/drm-lease-unstable-v1.xml @@ -0,0 +1,226 @@ +<?xml version="1.0" encoding="UTF-8"?> +<protocol name="drm_lease_unstable_v1"> + +<copyright> + Copyright 2018 NXP + + 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_kms_lease_manager_v1" version="1"> + <description summary="lease manager"> + This interface makes use of DRM lease written by Keith Packard. + + A DRM master can create another DRM master and ``lease'' resources it has + control over to the new DRM master. Once leased, resources can not be + controlled by the owner unless the owner cancels (revokes) the lease, or + the new DRM master is closed. + + A lease is a contract between the Lessor (DRM master which has leased out + resources to one or more other DRM masters) and a Lessee + (DRM master which controls resources leased from another DRM master). This + contract specifies which resources may be controlled by the Lessee. + + The Lessee can issue modesetting/page-flipping atomic operations etc., + just like a Lessor using the leased file-descriptor passed by the Lessor. + + Besides the leased file-descriptor, an integer is used to uniquely + identify a Lessee within the tree of DRM masters descending from a single + Owner. Once the Lessee has finished with the resources it had used, the + Lessee ID can be used to revoke that lease. + + Upon connecting to the compositor all leasable connectors will be + advertised to the client. These connectors are represented by + zwp_kms_lease_connector_v1 interface, and have to be "added" to a lease + request object before creating a lease object. This instructs the + compositor to use that connector when creating a lease. The client can + receive multiple events for multiple leasable connectors and needs a way + to discern between various leasable connectors. When receiving this + connector object, events will be sent gratuitously so that the + client can properly choose which connector wants to use. + + A lease request object is represented by zwp_kms_lease_request_v1 + interface and is used temporarily as a storage place for objects + IDs. Once the client has a lease object it can freely call its + destructor, zwp_kms_lease_request_v1::destroy. + + zwp_kms_lease_request_v1::created event will provide a lease object + represented by zwp_kms_lease_v1 interface. The client will then use + this lease object to retrieve the file-descriptor (leased fd) and + use it to perform mode-setting/atomic operations. + + Whilst the operation to revoke a lease requires a lesse id, in our case, + calling the destructor for the lease object will cause the lease to be + revoked. + + 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="destroy" type="destructor"> + <description summary="destroys the manager"> + Destroys the manager object and should be called last. + </description> + </request> + + <request name="create_lease_req"> + <description summary="create a temporary object for managing the lease"> + Create an object for temporarily storing all the KMS resources to be leased. + </description> + <arg name="params_id" type="new_id" interface="zwp_kms_lease_request_v1" + summary="the new temporary"/> + </request> + + <event name="connector"> + <description summary="advertise which connector can be used to request a lease"> + This event advertises a leasable connector object. When creating a + lease pass this object to zwp_kms_lease_request_v1::add_connector. As + multiple connectors can be leasable (based on compositor policy), + zwp_kms_lease_connector_v1 will send gratuitously events in order + to distinguish between different leasable connectors. + After the client has added (using + zwp_kms_lease_request_v1::add_connector) a leasable + connector object, zwp_kms_lease_request_v1::create request should be + called for creating a zwp_kms_lease_v1 lease object. + </description> + <arg name="conn_obj" type="new_id" interface="zwp_kms_lease_connector_v1" + summary="the new temporary" /> + </event> + + </interface> + + <interface name="zwp_kms_lease_v1" version="1"> + <description summary="the lease object itself"> + This interface represents the lease object and encapsulates the lease + properties. This objected is sent by zwp_kms_lease_request_v1::created + event. Use this object to retrieve lease properties. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroys the temporary lease request object"> + This request ask the compositor to revoke the lease, destroy the lease + object and free temporary storage. + </description> + </request> + + <request name="retrieve_leased_fd"> + <description summary="request to retrieve info about the lease"> + Request to retrieve the leased file-descriptor. + </description> + </request> + + <event name="leased_fd"> + <description summary="returns information about the lease"> + This event returns the leased fd which is required for modesetting + or querying page flips/atomic modesetting. + The client can use the leased fd to find out DRM-related information + like connector ID, CRTC ID, and plane ID using drmModeGetLease(). + Using that information it can derive a suitable mode useful + when performing a modeset. + </description> + <arg name="leased_fd" type="fd" summary="leased fd" /> + </event> + + </interface> + + <interface name="zwp_kms_lease_connector_v1" version="1"> + <description summary="zwp_kms_lease_connector_v1"> + This interface describes a connector object advertised by + zwp_kms_lease_manager_v1::connector. + </description> + + <event name="name"> + <description summary="name"> + Event sent gratuitously to the client representing the connector name. + </description> + <arg name="conn_name" type="string" summary="connector name" /> + </event> + + </interface> + + <interface name="zwp_kms_lease_request_v1" version="1"> + <description summary="lease request object"> + This interface is used for managing zwp_kms_lease_v1 object. It is used + to create a zwp_kms_lease_v1 object (the actual lease object), to revoke + it, and to specify from which connector the lease should be created. + </description> + + <request name="destroy" type="destructor"> + <description summary="destroys the lease request object"> + This destroys the lease request interface, and can be called once + the client obtained a zwp_kms_lease_v1 object. + </description> + </request> + + <request name="add_connector"> + <description summary="add a leasable connector object"> + This request is used to create the lease object using the leasable + connector object, and must be called before zwp_kms_lease_request_v1::create. + </description> + <arg name="conn_obj" type="object" interface="zwp_kms_lease_connector_v1" + summary="a leasable connector added to the lease"/> + </request> + + <request name="create"> + <description summary="create the lease"> + This request will create a zwp_kms_lease_v1 object based on + zwp_kms_lease_connector_v1 that was added using + zwp_kms_lease_request_v1::add_connector. + </description> + </request> + + <event name="created"> + <description summary="lease created successfully"> + This event indicates that the lease has been created. It provides a + zwp_kms_lease_v1 object used for retrieving the file-descriptor + representing the lease. + </description> + <arg name="lease_obj" type="new_id" interface="zwp_kms_lease_v1" + summary="the lease obj"/> + </event> + + <event name="failed"> + <description summary="lease could not be created"> + This event indicates that the lease could not be created. + </description> + </event> + + <event name="connector_add_failed"> + <description summary="failed to add connector"> + This event indicates that the leasable connector object specified in + zwp_kms_lease_request_v1::add_connector couldn't be added. + </description> + </event> + + <event name="connector_added"> + <description summary="connector was added successfully"> + This event indicates that the leasable connector object specified in + zwp_kms_lease_request_v1::add_connector has been added successfully. + </description> + </event> + + </interface> +</protocol> -- 2.9.3 _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/wayland-devel
