Skip to content
This repository has been archived by the owner on Nov 1, 2021. It is now read-only.

Commit

Permalink
Introduce wlr_drm_lease_v1
Browse files Browse the repository at this point in the history
  • Loading branch information
@ddevault
ddevault committed Sep 24, 2019
1 parent 1b96ba8 commit d84eb9e
Show file tree
Hide file tree
Showing 5 changed files with 975 additions and 0 deletions.
145 changes: 145 additions & 0 deletions include/wlr/types/wlr_drm_lease_v1.h
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
/*
* This an unstable interface of wlroots. No guarantees are made regarding the
* future consistency of this API.
*/
#ifndef WLR_USE_UNSTABLE
#error "Add -DWLR_USE_UNSTABLE to enable unstable wlroots features"
#endif

#ifndef WLR_TYPES_WLR_DRM_LEASE_V1_H
#define WLR_TYPES_WLR_DRM_LEASE_V1_H

#include <wayland-server.h>
#include <wlr/backend.h>

struct wlr_drm_backend;

struct wlr_drm_lease_manager_v1 {
struct wl_list resources; // wl_resource_get_link
struct wl_global *global;
struct wlr_drm_backend *backend;

struct wl_list connectors; // wlr_drm_lease_connector_v1::link
struct wl_list leases; // wl_resource_get_link
struct wl_list lease_requests; // wl_resource_get_link

struct {
/**
* Upon receiving this signal, call
* wlr_drm_lease_manager_v1_grant_lease_request to grant a lease of the
* requested DRM resources, or
* wlr_drm_lease_manager_v1_reject_lease_request to reject the request.
*/
struct wl_signal lease_requested; // wlr_drm_lease_request_v1
} events;

void *data;
};

struct wlr_drm_connector;
struct wlr_drm_lease_v1;

/** Represents a connector which is available for leasing, and may be leased */
struct wlr_drm_lease_connector_v1 {
struct wlr_output *output;
struct wlr_drm_connector *drm_connector;
struct wl_list resources; // wl_resource_get_link

/** NULL if no client is currently leasing this connector */
struct wlr_drm_lease_v1 *active_lease;

struct wl_list link; // wlr_drm_lease_manager_v1::connectors
};

/** Represents a connector which has been added to a lease or lease request */
struct wlr_drm_connector_lease_v1 {
struct wlr_drm_lease_manager_v1 *manager;
struct wlr_drm_lease_connector_v1 *connector;
struct wl_list link; // wlr_drm_lease_request_v1::connectors
};

/** Represents a pending or submitted lease request */
struct wlr_drm_lease_request_v1 {
struct wlr_drm_lease_manager_v1 *manager;
struct wl_resource *resource; // wlr_drm_manager_v1::lease_requests
struct wl_list connectors; // wlr_drm_connector_lease_v1::link
bool invalid;

/** NULL until the lease is submitted */
struct wlr_drm_lease_v1 *lease;
};

/** Represents an active or previously active lease */
struct wlr_drm_lease_v1 {
struct wlr_drm_lease_manager_v1 *manager;
struct wl_resource *resource; // wlr_drm_manager_v1::leases
struct wl_list connectors; // wlr_drm_connector_lease_v1::link
uint32_t lessee_id;

struct {
/**
* Upon receiving this signal, it is safe to re-use the leased
* resources. After the signal is processed, the backend will re-signal
* new_output events for each leased output.
*
* The lifetime of the lease reference after the signal handler returns
* is not defined.
*/
struct wl_signal revoked; // wlr_drm_lease_v1
} events;

void *data;
};

/**
* Creates a DRM lease manager. The backend supplied must be a DRM backend, or a
* multi-backend with a single DRM backend within. If the supplied backend is
* not suitable, NULL is returned.
*/
struct wlr_drm_lease_manager_v1 *wlr_drm_lease_manager_v1_create(
struct wl_display *display, struct wlr_backend *backend);

/**
* Offers a wlr_output for lease. The offered output must be owned by the DRM
* backend associated with this lease manager.
*/
void wlr_drm_lease_manager_v1_offer_output(
struct wlr_drm_lease_manager_v1 *manager, struct wlr_output *output);

/**
* Withdraws a previously offered output for lease. It is a programming error to
* call this function when there are any active leases for this output.
*/
void wlr_drm_lease_manager_v1_widthraw_output(
struct wlr_drm_lease_manager_v1 *manager, struct wlr_output *output);

/**
* Grants a client's lease request. The lease manager will then provision the
* DRM lease and transfer the file descriptor to the client. After calling this,
* each wlr_output leased is destroyed, and will be re-issued through
* wlr_backend.events.new_outputs when the lease is revoked.
*
* This will return NULL without leasing any resources if the lease is invalid;
* this can happen for example if two clients request the same resources and an
* attempt to grant both leases is made.
*/
struct wlr_drm_lease_v1 *wlr_drm_lease_manager_v1_grant_lease_request(
struct wlr_drm_lease_manager_v1 *manager,
struct wlr_drm_lease_request_v1 *request);

/**
* Rejects a client's lease request.
*/
void wlr_drm_lease_manager_v1_reject_lease_request(
struct wlr_drm_lease_manager_v1 *manager,
struct wlr_drm_lease_request_v1 *request);

/**
* Revokes a client's lease request. You may resume use of any of the outputs
* leased after making this call.
*/
void wlr_drm_lease_manager_v1_revoke_lease(
struct wlr_drm_lease_manager_v1 *manager,
struct wlr_drm_lease_v1 *lease);

#endif
246 changes: 246 additions & 0 deletions protocol/drm-lease-unstable-v1.xml
View file
Original file line number Diff line number Diff line change
@@ -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>
Loading

0 comments on commit d84eb9e

Please sign in to comment.