1<?xml version="1.0" encoding="UTF-8"?>
2<protocol name="linux_drm_syncobj_v1">
3 <copyright>
4 Copyright 2016 The Chromium Authors.
5 Copyright 2017 Intel Corporation
6 Copyright 2018 Collabora, Ltd
7 Copyright 2021 Simon Ser
8
9 Permission is hereby granted, free of charge, to any person obtaining a
10 copy of this software and associated documentation files (the "Software"),
11 to deal in the Software without restriction, including without limitation
12 the rights to use, copy, modify, merge, publish, distribute, sublicense,
13 and/or sell copies of the Software, and to permit persons to whom the
14 Software is furnished to do so, subject to the following conditions:
15
16 The above copyright notice and this permission notice (including the next
17 paragraph) shall be included in all copies or substantial portions of the
18 Software.
19
20 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
23 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
25 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
26 DEALINGS IN THE SOFTWARE.
27 </copyright>
28
29 <description summary="protocol for providing explicit synchronization">
30 This protocol allows clients to request explicit synchronization for
31 buffers. It is tied to the Linux DRM synchronization object framework.
32
33 Synchronization refers to co-ordination of pipelined operations performed
34 on buffers. Most GPU clients will schedule an asynchronous operation to
35 render to the buffer, then immediately send the buffer to the compositor
36 to be attached to a surface.
37
38 With implicit synchronization, ensuring that the rendering operation is
39 complete before the compositor displays the buffer is an implementation
40 detail handled by either the kernel or userspace graphics driver.
41
42 By contrast, with explicit synchronization, DRM synchronization object
43 timeline points mark when the asynchronous operations are complete. When
44 submitting a buffer, the client provides a timeline point which will be
45 waited on before the compositor accesses the buffer, and another timeline
46 point that the compositor will signal when it no longer needs to access the
47 buffer contents for the purposes of the surface commit.
48
49 Linux DRM synchronization objects are documented at:
50 https://dri.freedesktop.org/docs/drm/gpu/drm-mm.html#drm-sync-objects
51
52 Warning! The protocol described in this file is currently in the testing
53 phase. Backward compatible changes may be added together with the
54 corresponding interface version bump. Backward incompatible changes can
55 only be done by creating a new major version of the extension.
56 </description>
57
58 <interface name="wp_linux_drm_syncobj_manager_v1" version="1">
59 <description summary="global for providing explicit synchronization">
60 This global is a factory interface, allowing clients to request
61 explicit synchronization for buffers on a per-surface basis.
62
63 See wp_linux_drm_syncobj_surface_v1 for more information.
64 </description>
65
66 <request name="destroy" type="destructor">
67 <description summary="destroy explicit synchronization factory object">
68 Destroy this explicit synchronization factory object. Other objects
69 shall not be affected by this request.
70 </description>
71 </request>
72
73 <enum name="error">
74 <entry name="surface_exists" value="0"
75 summary="the surface already has a synchronization object associated"/>
76 <entry name="invalid_timeline" value="1"
77 summary="the timeline object could not be imported"/>
78 </enum>
79
80 <request name="get_surface">
81 <description summary="extend surface interface for explicit synchronization">
82 Instantiate an interface extension for the given wl_surface to provide
83 explicit synchronization.
84
85 If the given wl_surface already has an explicit synchronization object
86 associated, the surface_exists protocol error is raised.
87
88 Graphics APIs, like EGL or Vulkan, that manage the buffer queue and
89 commits of a wl_surface themselves, are likely to be using this
90 extension internally. If a client is using such an API for a
91 wl_surface, it should not directly use this extension on that surface,
92 to avoid raising a surface_exists protocol error.
93 </description>
94 <arg name="id" type="new_id" interface="wp_linux_drm_syncobj_surface_v1"
95 summary="the new synchronization surface object id"/>
96 <arg name="surface" type="object" interface="wl_surface"
97 summary="the surface"/>
98 </request>
99
100 <request name="import_timeline">
101 <description summary="import a DRM syncobj timeline">
102 Import a DRM synchronization object timeline.
103
104 If the FD cannot be imported, the invalid_timeline error is raised.
105 </description>
106 <arg name="id" type="new_id" interface="wp_linux_drm_syncobj_timeline_v1"/>
107 <arg name="fd" type="fd" summary="drm_syncobj file descriptor"/>
108 </request>
109 </interface>
110
111 <interface name="wp_linux_drm_syncobj_timeline_v1" version="1">
112 <description summary="synchronization object timeline">
113 This object represents an explicit synchronization object timeline
114 imported by the client to the compositor.
115 </description>
116
117 <request name="destroy" type="destructor">
118 <description summary="destroy the timeline">
119 Destroy the synchronization object timeline. Other objects are not
120 affected by this request, in particular timeline points set by
121 set_acquire_point and set_release_point are not unset.
122 </description>
123 </request>
124 </interface>
125
126 <interface name="wp_linux_drm_syncobj_surface_v1" version="1">
127 <description summary="per-surface explicit synchronization">
128 This object is an add-on interface for wl_surface to enable explicit
129 synchronization.
130
131 Each surface can be associated with only one object of this interface at
132 any time.
133
134 Explicit synchronization is guaranteed to be supported for buffers
135 created with any version of the linux-dmabuf protocol. Compositors are
136 free to support explicit synchronization for additional buffer types.
137 If at surface commit time the attached buffer does not support explicit
138 synchronization, an unsupported_buffer error is raised.
139
140 As long as the wp_linux_drm_syncobj_surface_v1 object is alive, the
141 compositor may ignore implicit synchronization for buffers attached and
142 committed to the wl_surface. The delivery of wl_buffer.release events
143 for buffers attached to the surface becomes undefined.
144
145 Clients must set both acquire and release points if and only if a
146 non-null buffer is attached in the same surface commit. See the
147 no_buffer, no_acquire_point and no_release_point protocol errors.
148
149 If at surface commit time the acquire and release DRM syncobj timelines
150 are identical, the acquire point value must be strictly less than the
151 release point value, or else the conflicting_points protocol error is
152 raised.
153 </description>
154
155 <request name="destroy" type="destructor">
156 <description summary="destroy the surface synchronization object">
157 Destroy this surface synchronization object.
158
159 Any timeline point set by this object with set_acquire_point or
160 set_release_point since the last commit may be discarded by the
161 compositor. Any timeline point set by this object before the last
162 commit will not be affected.
163 </description>
164 </request>
165
166 <enum name="error">
167 <entry name="no_surface" value="1"
168 summary="the associated wl_surface was destroyed"/>
169 <entry name="unsupported_buffer" value="2"
170 summary="the buffer does not support explicit synchronization"/>
171 <entry name="no_buffer" value="3" summary="no buffer was attached"/>
172 <entry name="no_acquire_point" value="4"
173 summary="no acquire timeline point was set"/>
174 <entry name="no_release_point" value="5"
175 summary="no release timeline point was set"/>
176 <entry name="conflicting_points" value="6"
177 summary="acquire and release timeline points are in conflict"/>
178 </enum>
179
180 <request name="set_acquire_point">
181 <description summary="set the acquire timeline point">
182 Set the timeline point that must be signalled before the compositor may
183 sample from the buffer attached with wl_surface.attach.
184
185 The 64-bit unsigned value combined from point_hi and point_lo is the
186 point value.
187
188 The acquire point is double-buffered state, and will be applied on the
189 next wl_surface.commit request for the associated surface. Thus, it
190 applies only to the buffer that is attached to the surface at commit
191 time.
192
193 If an acquire point has already been attached during the same commit
194 cycle, the new point replaces the old one.
195
196 If the associated wl_surface was destroyed, a no_surface error is
197 raised.
198
199 If at surface commit time there is a pending acquire timeline point set
200 but no pending buffer attached, a no_buffer error is raised. If at
201 surface commit time there is a pending buffer attached but no pending
202 acquire timeline point set, the no_acquire_point protocol error is
203 raised.
204 </description>
205 <arg name="timeline" type="object" interface="wp_linux_drm_syncobj_timeline_v1"/>
206 <arg name="point_hi" type="uint" summary="high 32 bits of the point value"/>
207 <arg name="point_lo" type="uint" summary="low 32 bits of the point value"/>
208 </request>
209
210 <request name="set_release_point">
211 <description summary="set the release timeline point">
212 Set the timeline point that must be signalled by the compositor when it
213 has finished its usage of the buffer attached with wl_surface.attach
214 for the relevant commit.
215
216 Once the timeline point is signaled, and assuming the associated buffer
217 is not pending release from other wl_surface.commit requests, no
218 additional explicit or implicit synchronization with the compositor is
219 required to safely re-use the buffer.
220
221 Note that clients cannot rely on the release point being always
222 signaled after the acquire point: compositors may release buffers
223 without ever reading from them. In addition, the compositor may use
224 different presentation paths for different commits, which may have
225 different release behavior. As a result, the compositor may signal the
226 release points in a different order than the client committed them.
227
228 Because signaling a timeline point also signals every previous point,
229 it is generally not safe to use the same timeline object for the
230 release points of multiple buffers. The out-of-order signaling
231 described above may lead to a release point being signaled before the
232 compositor has finished reading. To avoid this, it is strongly
233 recommended that each buffer should use a separate timeline for its
234 release points.
235
236 The 64-bit unsigned value combined from point_hi and point_lo is the
237 point value.
238
239 The release point is double-buffered state, and will be applied on the
240 next wl_surface.commit request for the associated surface. Thus, it
241 applies only to the buffer that is attached to the surface at commit
242 time.
243
244 If a release point has already been attached during the same commit
245 cycle, the new point replaces the old one.
246
247 If the associated wl_surface was destroyed, a no_surface error is
248 raised.
249
250 If at surface commit time there is a pending release timeline point set
251 but no pending buffer attached, a no_buffer error is raised. If at
252 surface commit time there is a pending buffer attached but no pending
253 release timeline point set, the no_release_point protocol error is
254 raised.
255 </description>
256 <arg name="timeline" type="object" interface="wp_linux_drm_syncobj_timeline_v1"/>
257 <arg name="point_hi" type="uint" summary="high 32 bits of the point value"/>
258 <arg name="point_lo" type="uint" summary="low 32 bits of the point value"/>
259 </request>
260 </interface>
261</protocol>