1<?xml version="1.0" encoding="UTF-8"?> 2<protocol name="linux_dmabuf_unstable_v1"> 3 4 <copyright> 5 Copyright © 2014, 2015 Collabora, Ltd. 6 7 Permission is hereby granted, free of charge, to any person obtaining a 8 copy of this software and associated documentation files (the "Software"), 9 to deal in the Software without restriction, including without limitation 10 the rights to use, copy, modify, merge, publish, distribute, sublicense, 11 and/or sell copies of the Software, and to permit persons to whom the 12 Software is furnished to do so, subject to the following conditions: 13 14 The above copyright notice and this permission notice (including the next 15 paragraph) shall be included in all copies or substantial portions of the 16 Software. 17 18 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 21 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 23 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 24 DEALINGS IN THE SOFTWARE. 25 </copyright> 26 27 <interface name="zwp_linux_dmabuf_v1" version="3"> 28 <description summary="factory for creating dmabuf-based wl_buffers"> 29 Following the interfaces from: 30 https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt 31 https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt 32 and the Linux DRM sub-system's AddFb2 ioctl. 33 34 This interface offers ways to create generic dmabuf-based 35 wl_buffers. Immediately after a client binds to this interface, 36 the set of supported formats and format modifiers is sent with 37 'format' and 'modifier' events. 38 39 The following are required from clients: 40 41 - Clients must ensure that either all data in the dma-buf is 42 coherent for all subsequent read access or that coherency is 43 correctly handled by the underlying kernel-side dma-buf 44 implementation. 45 46 - Don't make any more attachments after sending the buffer to the 47 compositor. Making more attachments later increases the risk of 48 the compositor not being able to use (re-import) an existing 49 dmabuf-based wl_buffer. 50 51 The underlying graphics stack must ensure the following: 52 53 - The dmabuf file descriptors relayed to the server will stay valid 54 for the whole lifetime of the wl_buffer. This means the server may 55 at any time use those fds to import the dmabuf into any kernel 56 sub-system that might accept it. 57 58 However, when the underlying graphics stack fails to deliver the 59 promise, because of e.g. a device hot-unplug which raises internal 60 errors, after the wl_buffer has been successfully created the 61 compositor must not raise protocol errors to the client when dmabuf 62 import later fails. 63 64 To create a wl_buffer from one or more dmabufs, a client creates a 65 zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params 66 request. All planes required by the intended format are added with 67 the 'add' request. Finally, a 'create' or 'create_immed' request is 68 issued, which has the following outcome depending on the import success. 69 70 The 'create' request, 71 - on success, triggers a 'created' event which provides the final 72 wl_buffer to the client. 73 - on failure, triggers a 'failed' event to convey that the server 74 cannot use the dmabufs received from the client. 75 76 For the 'create_immed' request, 77 - on success, the server immediately imports the added dmabufs to 78 create a wl_buffer. No event is sent from the server in this case. 79 - on failure, the server can choose to either: 80 - terminate the client by raising a fatal error. 81 - mark the wl_buffer as failed, and send a 'failed' event to the 82 client. If the client uses a failed wl_buffer as an argument to any 83 request, the behaviour is compositor implementation-defined. 84 85 Warning! The protocol described in this file is experimental and 86 backward incompatible changes may be made. Backward compatible changes 87 may be added together with the corresponding interface version bump. 88 Backward incompatible changes are done by bumping the version number in 89 the protocol and interface names and resetting the interface version. 90 Once the protocol is to be declared stable, the 'z' prefix and the 91 version number in the protocol and interface names are removed and the 92 interface version number is reset. 93 </description> 94 95 <request name="destroy" type="destructor"> 96 <description summary="unbind the factory"> 97 Objects created through this interface, especially wl_buffers, will 98 remain valid. 99 </description> 100 </request> 101 102 <request name="create_params"> 103 <description summary="create a temporary object for buffer parameters"> 104 This temporary object is used to collect multiple dmabuf handles into 105 a single batch to create a wl_buffer. It can only be used once and 106 should be destroyed after a 'created' or 'failed' event has been 107 received. 108 </description> 109 <arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1" 110 summary="the new temporary"/> 111 </request> 112 113 <event name="format"> 114 <description summary="supported buffer format"> 115 This event advertises one buffer format that the server supports. 116 All the supported formats are advertised once when the client 117 binds to this interface. A roundtrip after binding guarantees 118 that the client has received all supported formats. 119 120 For the definition of the format codes, see the 121 zwp_linux_buffer_params_v1::create request. 122 123 Warning: the 'format' event is likely to be deprecated and replaced 124 with the 'modifier' event introduced in zwp_linux_dmabuf_v1 125 version 3, described below. Please refrain from using the information 126 received from this event. 127 </description> 128 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 129 </event> 130 131 <event name="modifier" since="3"> 132 <description summary="supported buffer format modifier"> 133 This event advertises the formats that the server supports, along with 134 the modifiers supported for each format. All the supported modifiers 135 for all the supported formats are advertised once when the client 136 binds to this interface. A roundtrip after binding guarantees that 137 the client has received all supported format-modifier pairs. 138 139 For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi == 140 0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event. 141 It indicates that the server can support the format with an implicit 142 modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it 143 is as if no explicit modifier is specified. The effective modifier 144 will be derived from the dmabuf. 145 146 A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for 147 a given format supports both explicit modifiers and implicit modifiers. 148 149 For the definition of the format and modifier codes, see the 150 zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add 151 requests. 152 </description> 153 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 154 <arg name="modifier_hi" type="uint" 155 summary="high 32 bits of layout modifier"/> 156 <arg name="modifier_lo" type="uint" 157 summary="low 32 bits of layout modifier"/> 158 </event> 159 </interface> 160 161 <interface name="zwp_linux_buffer_params_v1" version="3"> 162 <description summary="parameters for creating a dmabuf-based wl_buffer"> 163 This temporary object is a collection of dmabufs and other 164 parameters that together form a single logical buffer. The temporary 165 object may eventually create one wl_buffer unless cancelled by 166 destroying it before requesting 'create'. 167 168 Single-planar formats only require one dmabuf, however 169 multi-planar formats may require more than one dmabuf. For all 170 formats, an 'add' request must be called once per plane (even if the 171 underlying dmabuf fd is identical). 172 173 You must use consecutive plane indices ('plane_idx' argument for 'add') 174 from zero to the number of planes used by the drm_fourcc format code. 175 All planes required by the format must be given exactly once, but can 176 be given in any order. Each plane index can be set only once. 177 </description> 178 179 <enum name="error"> 180 <entry name="already_used" value="0" 181 summary="the dmabuf_batch object has already been used to create a wl_buffer"/> 182 <entry name="plane_idx" value="1" 183 summary="plane index out of bounds"/> 184 <entry name="plane_set" value="2" 185 summary="the plane index was already set"/> 186 <entry name="incomplete" value="3" 187 summary="missing or too many planes to create a buffer"/> 188 <entry name="invalid_format" value="4" 189 summary="format not supported"/> 190 <entry name="invalid_dimensions" value="5" 191 summary="invalid width or height"/> 192 <entry name="out_of_bounds" value="6" 193 summary="offset + stride * height goes out of dmabuf bounds"/> 194 <entry name="invalid_wl_buffer" value="7" 195 summary="invalid wl_buffer resulted from importing dmabufs via 196 the create_immed request on given buffer_params"/> 197 </enum> 198 199 <request name="destroy" type="destructor"> 200 <description summary="delete this object, used or not"> 201 Cleans up the temporary data sent to the server for dmabuf-based 202 wl_buffer creation. 203 </description> 204 </request> 205 206 <request name="add"> 207 <description summary="add a dmabuf to the temporary set"> 208 This request adds one dmabuf to the set in this 209 zwp_linux_buffer_params_v1. 210 211 The 64-bit unsigned value combined from modifier_hi and modifier_lo 212 is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the 213 fb modifier, which is defined in drm_mode.h of Linux UAPI. 214 This is an opaque token. Drivers use this token to express tiling, 215 compression, etc. driver-specific modifications to the base format 216 defined by the DRM fourcc code. 217 218 Warning: It should be an error if the format/modifier pair was not 219 advertised with the modifier event. This is not enforced yet because 220 some implementations always accept DRM_FORMAT_MOD_INVALID. Also 221 version 2 of this protocol does not have the modifier event. 222 223 This request raises the PLANE_IDX error if plane_idx is too large. 224 The error PLANE_SET is raised if attempting to set a plane that 225 was already set. 226 </description> 227 <arg name="fd" type="fd" summary="dmabuf fd"/> 228 <arg name="plane_idx" type="uint" summary="plane index"/> 229 <arg name="offset" type="uint" summary="offset in bytes"/> 230 <arg name="stride" type="uint" summary="stride in bytes"/> 231 <arg name="modifier_hi" type="uint" 232 summary="high 32 bits of layout modifier"/> 233 <arg name="modifier_lo" type="uint" 234 summary="low 32 bits of layout modifier"/> 235 </request> 236 237 <enum name="flags" bitfield="true"> 238 <entry name="y_invert" value="1" summary="contents are y-inverted"/> 239 <entry name="interlaced" value="2" summary="content is interlaced"/> 240 <entry name="bottom_first" value="4" summary="bottom field first"/> 241 </enum> 242 243 <request name="create"> 244 <description summary="create a wl_buffer from the given dmabufs"> 245 This asks for creation of a wl_buffer from the added dmabuf 246 buffers. The wl_buffer is not created immediately but returned via 247 the 'created' event if the dmabuf sharing succeeds. The sharing 248 may fail at runtime for reasons a client cannot predict, in 249 which case the 'failed' event is triggered. 250 251 The 'format' argument is a DRM_FORMAT code, as defined by the 252 libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the 253 authoritative source on how the format codes should work. 254 255 The 'flags' is a bitfield of the flags defined in enum "flags". 256 'y_invert' means the that the image needs to be y-flipped. 257 258 Flag 'interlaced' means that the frame in the buffer is not 259 progressive as usual, but interlaced. An interlaced buffer as 260 supported here must always contain both top and bottom fields. 261 The top field always begins on the first pixel row. The temporal 262 ordering between the two fields is top field first, unless 263 'bottom_first' is specified. It is undefined whether 'bottom_first' 264 is ignored if 'interlaced' is not set. 265 266 This protocol does not convey any information about field rate, 267 duration, or timing, other than the relative ordering between the 268 two fields in one buffer. A compositor may have to estimate the 269 intended field rate from the incoming buffer rate. It is undefined 270 whether the time of receiving wl_surface.commit with a new buffer 271 attached, applying the wl_surface state, wl_surface.frame callback 272 trigger, presentation, or any other point in the compositor cycle 273 is used to measure the frame or field times. There is no support 274 for detecting missed or late frames/fields/buffers either, and 275 there is no support whatsoever for cooperating with interlaced 276 compositor output. 277 278 The composited image quality resulting from the use of interlaced 279 buffers is explicitly undefined. A compositor may use elaborate 280 hardware features or software to deinterlace and create progressive 281 output frames from a sequence of interlaced input buffers, or it 282 may produce substandard image quality. However, compositors that 283 cannot guarantee reasonable image quality in all cases are recommended 284 to just reject all interlaced buffers. 285 286 Any argument errors, including non-positive width or height, 287 mismatch between the number of planes and the format, bad 288 format, bad offset or stride, may be indicated by fatal protocol 289 errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, 290 OUT_OF_BOUNDS. 291 292 Dmabuf import errors in the server that are not obvious client 293 bugs are returned via the 'failed' event as non-fatal. This 294 allows attempting dmabuf sharing and falling back in the client 295 if it fails. 296 297 This request can be sent only once in the object's lifetime, after 298 which the only legal request is destroy. This object should be 299 destroyed after issuing a 'create' request. Attempting to use this 300 object after issuing 'create' raises ALREADY_USED protocol error. 301 302 It is not mandatory to issue 'create'. If a client wants to 303 cancel the buffer creation, it can just destroy this object. 304 </description> 305 <arg name="width" type="int" summary="base plane width in pixels"/> 306 <arg name="height" type="int" summary="base plane height in pixels"/> 307 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 308 <arg name="flags" type="uint" enum="flags" summary="see enum flags"/> 309 </request> 310 311 <event name="created"> 312 <description summary="buffer creation succeeded"> 313 This event indicates that the attempted buffer creation was 314 successful. It provides the new wl_buffer referencing the dmabuf(s). 315 316 Upon receiving this event, the client should destroy the 317 zlinux_dmabuf_params object. 318 </description> 319 <arg name="buffer" type="new_id" interface="wl_buffer" 320 summary="the newly created wl_buffer"/> 321 </event> 322 323 <event name="failed"> 324 <description summary="buffer creation failed"> 325 This event indicates that the attempted buffer creation has 326 failed. It usually means that one of the dmabuf constraints 327 has not been fulfilled. 328 329 Upon receiving this event, the client should destroy the 330 zlinux_buffer_params object. 331 </description> 332 </event> 333 334 <request name="create_immed" since="2"> 335 <description summary="immediately create a wl_buffer from the given 336 dmabufs"> 337 This asks for immediate creation of a wl_buffer by importing the 338 added dmabufs. 339 340 In case of import success, no event is sent from the server, and the 341 wl_buffer is ready to be used by the client. 342 343 Upon import failure, either of the following may happen, as seen fit 344 by the implementation: 345 - the client is terminated with one of the following fatal protocol 346 errors: 347 - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS, 348 in case of argument errors such as mismatch between the number 349 of planes and the format, bad format, non-positive width or 350 height, or bad offset or stride. 351 - INVALID_WL_BUFFER, in case the cause for failure is unknown or 352 plaform specific. 353 - the server creates an invalid wl_buffer, marks it as failed and 354 sends a 'failed' event to the client. The result of using this 355 invalid wl_buffer as an argument in any request by the client is 356 defined by the compositor implementation. 357 358 This takes the same arguments as a 'create' request, and obeys the 359 same restrictions. 360 </description> 361 <arg name="buffer_id" type="new_id" interface="wl_buffer" 362 summary="id for the newly created wl_buffer"/> 363 <arg name="width" type="int" summary="base plane width in pixels"/> 364 <arg name="height" type="int" summary="base plane height in pixels"/> 365 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 366 <arg name="flags" type="uint" enum="flags" summary="see enum flags"/> 367 </request> 368 369 </interface> 370 371</protocol> 372