1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="drm_lease_v1">
3 <copyright>
4 Copyright © 2018 NXP
5 Copyright © 2019 Status Research & Development GmbH.
6 Copyright © 2021 Xaver Hugl
7
8 Permission is hereby granted, free of charge, to any person obtaining a
9 copy of this software and associated documentation files (the "Software"),
10 to deal in the Software without restriction, including without limitation
11 the rights to use, copy, modify, merge, publish, distribute, sublicense,
12 and/or sell copies of the Software, and to permit persons to whom the
13 Software is furnished to do so, subject to the following conditions:
14
15 The above copyright notice and this permission notice (including the next
16 paragraph) shall be included in all copies or substantial portions of the
17 Software.
18
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
22 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
24 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
25 DEALINGS IN THE SOFTWARE.
26 </copyright>
27
28 <interface name="wp_drm_lease_device_v1" version="1">
29 <description summary="lease device">
30 This protocol is used by Wayland compositors which act as Direct
31 Rendering Manager (DRM) masters to lease DRM resources to Wayland
32 clients.
33
34 The compositor will advertise one wp_drm_lease_device_v1 global for each
35 DRM node. Some time after a client binds to the wp_drm_lease_device_v1
36 global, the compositor will send a drm_fd event followed by zero, one or
37 more connector events. After all currently available connectors have been
38 sent, the compositor will send a wp_drm_lease_device_v1.done event.
39
40 When the list of connectors available for lease changes the compositor
41 will send wp_drm_lease_device_v1.connector events for added connectors and
42 wp_drm_lease_connector_v1.withdrawn events for removed connectors,
43 followed by a wp_drm_lease_device_v1.done event.
44
45 The compositor will indicate when a device is gone by removing the global
46 via a wl_registry.global_remove event. Upon receiving this event, the
47 client should destroy any matching wp_drm_lease_device_v1 object.
48
49 To destroy a wp_drm_lease_device_v1 object, the client must first issue
50 a release request. Upon receiving this request, the compositor will
51 immediately send a released event and destroy the object. The client must
52 continue to process and discard drm_fd and connector events until it
53 receives the released event. Upon receiving the released event, the
54 client can safely cleanup any client-side resources.
55
56 Warning! The protocol described in this file is currently in the testing
57 phase. Backward compatible changes may be added together with the
58 corresponding interface version bump. Backward incompatible changes can
59 only be done by creating a new major version of the extension.
60 </description>
61
62 <request name="create_lease_request">
63 <description summary="create a lease request object">
64 Creates a lease request object.
65
66 See the documentation for wp_drm_lease_request_v1 for details.
67 </description>
68 <arg name="id" type="new_id" interface="wp_drm_lease_request_v1" />
69 </request>
70
71 <request name="release">
72 <description summary="release this object">
73 Indicates the client no longer wishes to use this object. In response
74 the compositor will immediately send the released event and destroy
75 this object. It can however not guarantee that the client won't receive
76 connector events before the released event. The client must not send any
77 requests after this one, doing so will raise a wl_display error.
78 Existing connectors, lease request and leases will not be affected.
79 </description>
80 </request>
81
82 <event name="drm_fd">
83 <description summary="open a non-master fd for this DRM node">
84 The compositor will send this event when the wp_drm_lease_device_v1
85 global is bound, although there are no guarantees as to how long this
86 takes - the compositor might need to wait until regaining DRM master.
87 The included fd is a non-master DRM file descriptor opened for this
88 device and the compositor must not authenticate it.
89 The purpose of this event is to give the client the ability to
90 query DRM and discover information which may help them pick the
91 appropriate DRM device or select the appropriate connectors therein.
92 </description>
93 <arg name="fd" type="fd" summary="DRM file descriptor" />
94 </event>
95
96 <event name="connector">
97 <description summary="advertise connectors available for leases">
98 The compositor will use this event to advertise connectors available for
99 lease by clients. This object may be passed into a lease request to
100 indicate the client would like to lease that connector, see
101 wp_drm_lease_request_v1.request_connector for details. While the
102 compositor will make a best effort to not send disconnected connectors,
103 no guarantees can be made.
104
105 The compositor must send the drm_fd event before sending connectors.
106 After the drm_fd event it will send all available connectors but may
107 send additional connectors at any time.
108 </description>
109 <arg name="id" type="new_id" interface="wp_drm_lease_connector_v1" />
110 </event>
111
112 <event name="done">
113 <description summary="signals grouping of connectors">
114 The compositor will send this event to indicate that it has sent all
115 currently available connectors after the client binds to the global or
116 when it updates the connector list, for example on hotplug, drm master
117 change or when a leased connector becomes available again. It will
118 similarly send this event to group wp_drm_lease_connector_v1.withdrawn
119 events of connectors of this device.
120 </description>
121 </event>
122
123 <event name="released" type="destructor">
124 <description summary="the compositor has finished using the device">
125 This event is sent in response to the release request and indicates
126 that the compositor is done sending connector events.
127 The compositor will destroy this object immediately after sending the
128 event and it will become invalid. The client should release any
129 resources associated with this device after receiving this event.
130 </description>
131 </event>
132 </interface>
133
134 <interface name="wp_drm_lease_connector_v1" version="1">
135 <description summary="a leasable DRM connector">
136 Represents a DRM connector which is available for lease. These objects are
137 created via wp_drm_lease_device_v1.connector events, and should be passed
138 to lease requests via wp_drm_lease_request_v1.request_connector.
139 Immediately after the wp_drm_lease_connector_v1 object is created the
140 compositor will send a name, a description, a connector_id and a done
141 event. When the description is updated the compositor will send a
142 description event followed by a done event.
143 </description>
144
145 <event name="name">
146 <description summary="name">
147 The compositor sends this event once the connector is created to
148 indicate the name of this connector. This will not change for the
149 duration of the Wayland session, but is not guaranteed to be consistent
150 between sessions.
151
152 If the compositor supports wl_output version 4 and this connector
153 corresponds to a wl_output, the compositor should use the same name as
154 for the wl_output.
155 </description>
156 <arg name="name" type="string" summary="connector name" />
157 </event>
158
159 <event name="description">
160 <description summary="description">
161 The compositor sends this event once the connector is created to provide
162 a human-readable description for this connector, which may be presented
163 to the user. The compositor may send this event multiple times over the
164 lifetime of this object to reflect changes in the description.
165 </description>
166 <arg name="description" type="string" summary="connector description" />
167 </event>
168
169 <event name="connector_id">
170 <description summary="connector_id">
171 The compositor sends this event once the connector is created to
172 indicate the DRM object ID which represents the underlying connector
173 that is being offered. Note that the final lease may include additional
174 object IDs, such as CRTCs and planes.
175 </description>
176 <arg name="connector_id" type="uint" summary="DRM connector ID" />
177 </event>
178
179 <event name="done">
180 <description summary="all properties have been sent">
181 This event is sent after all properties of a connector have been sent.
182 This allows changes to the properties to be seen as atomic even if they
183 happen via multiple events.
184 </description>
185 </event>
186
187 <event name="withdrawn">
188 <description summary="lease offer withdrawn">
189 Sent to indicate that the compositor will no longer honor requests for
190 DRM leases which include this connector. The client may still issue a
191 lease request including this connector, but the compositor will send
192 wp_drm_lease_v1.finished without issuing a lease fd. Compositors are
193 encouraged to send this event when they lose access to connector, for
194 example when the connector is hot-unplugged, when the connector gets
195 leased to a client or when the compositor loses DRM master.
196
197 If a client holds a lease for the connector, the status of the lease
198 remains the same. The client should destroy the object after receiving
199 this event.
200 </description>
201 </event>
202
203 <request name="destroy" type="destructor">
204 <description summary="destroy connector">
205 The client may send this request to indicate that it will not use this
206 connector. Clients are encouraged to send this after receiving the
207 "withdrawn" event so that the server can release the resources
208 associated with this connector offer. Neither existing lease requests
209 nor leases will be affected.
210 </description>
211 </request>
212 </interface>
213
214 <interface name="wp_drm_lease_request_v1" version="1">
215 <description summary="DRM lease request">
216 A client that wishes to lease DRM resources will attach the list of
217 connectors advertised with wp_drm_lease_device_v1.connector that they
218 wish to lease, then use wp_drm_lease_request_v1.submit to submit the
219 request.
220 </description>
221
222 <enum name="error">
223 <entry name="wrong_device" value="0"
224 summary="requested a connector from a different lease device"/>
225 <entry name="duplicate_connector" value="1"
226 summary="requested a connector twice"/>
227 <entry name="empty_lease" value="2"
228 summary="requested a lease without requesting a connector"/>
229 </enum>
230
231 <request name="request_connector">
232 <description summary="request a connector for this lease">
233 Indicates that the client would like to lease the given connector.
234 This is only used as a suggestion, the compositor may choose to
235 include any resources in the lease it issues, or change the set of
236 leased resources at any time. Compositors are however encouraged to
237 include the requested connector and other resources necessary
238 to drive the connected output in the lease.
239
240 Requesting a connector that was created from a different lease device
241 than this lease request raises the wrong_device error. Requesting a
242 connector twice will raise the duplicate_connector error.
243 </description>
244 <arg name="connector" type="object"
245 interface="wp_drm_lease_connector_v1" />
246 </request>
247
248 <request name="submit" type="destructor">
249 <description summary="submit the lease request">
250 Submits the lease request and creates a new wp_drm_lease_v1 object.
251 After calling submit the compositor will immediately destroy this
252 object, issuing any more requests will cause a wl_display error.
253 The compositor doesn't make any guarantees about the events of the
254 lease object, clients cannot expect an immediate response.
255 Not requesting any connectors before submitting the lease request
256 will raise the empty_lease error.
257 </description>
258 <arg name="id" type="new_id" interface="wp_drm_lease_v1" />
259 </request>
260 </interface>
261
262 <interface name="wp_drm_lease_v1" version="1">
263 <description summary="a DRM lease">
264 A DRM lease object is used to transfer the DRM file descriptor to the
265 client and manage the lifetime of the lease.
266
267 Some time after the wp_drm_lease_v1 object is created, the compositor
268 will reply with the lease request's result. If the lease request is
269 granted, the compositor will send a lease_fd event. If the lease request
270 is denied, the compositor will send a finished event without a lease_fd
271 event.
272 </description>
273
274 <event name="lease_fd">
275 <description summary="shares the DRM file descriptor">
276 This event returns a file descriptor suitable for use with DRM-related
277 ioctls. The client should use drmModeGetLease to enumerate the DRM
278 objects which have been leased to them. The compositor guarantees it
279 will not use the leased DRM objects itself until it sends the finished
280 event. If the compositor cannot or will not grant a lease for the
281 requested connectors, it will not send this event, instead sending the
282 finished event.
283
284 The compositor will send this event at most once during this objects
285 lifetime.
286 </description>
287 <arg name="leased_fd" type="fd" summary="leased DRM file descriptor" />
288 </event>
289
290 <event name="finished">
291 <description summary="sent when the lease has been revoked">
292 The compositor uses this event to either reject a lease request, or if
293 it previously sent a lease_fd, to notify the client that the lease has
294 been revoked. If the client requires a new lease, they should destroy
295 this object and submit a new lease request. The compositor will send
296 no further events for this object after sending the finish event.
297 Compositors should revoke the lease when any of the leased resources
298 become unavailable, namely when a hot-unplug occurs or when the
299 compositor loses DRM master. Compositors may advertise the connector
300 for leasing again, if the resource is available, by sending the
301 connector event through the wp_drm_lease_device_v1 interface.
302 </description>
303 </event>
304
305 <request name="destroy" type="destructor">
306 <description summary="destroys the lease object">
307 The client should send this to indicate that it no longer wishes to use
308 this lease. The compositor should use drmModeRevokeLease on the
309 appropriate file descriptor, if necessary.
310
311 Upon destruction, the compositor should advertise the connector for
312 leasing again by sending the connector event through the
313 wp_drm_lease_device_v1 interface.
314 </description>
315 </request>
316 </interface>
317</protocol>