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 To create a wl_buffer from one or more dmabufs, a client creates a 59 zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params 60 request. All planes required by the intended format are added with 61 the 'add' request. Finally, a 'create' or 'create_immed' request is 62 issued, which has the following outcome depending on the import success. 63 64 The 'create' request, 65 - on success, triggers a 'created' event which provides the final 66 wl_buffer to the client. 67 - on failure, triggers a 'failed' event to convey that the server 68 cannot use the dmabufs received from the client. 69 70 For the 'create_immed' request, 71 - on success, the server immediately imports the added dmabufs to 72 create a wl_buffer. No event is sent from the server in this case. 73 - on failure, the server can choose to either: 74 - terminate the client by raising a fatal error. 75 - mark the wl_buffer as failed, and send a 'failed' event to the 76 client. If the client uses a failed wl_buffer as an argument to any 77 request, the behaviour is compositor implementation-defined. 78 79 Warning! The protocol described in this file is experimental and 80 backward incompatible changes may be made. Backward compatible changes 81 may be added together with the corresponding interface version bump. 82 Backward incompatible changes are done by bumping the version number in 83 the protocol and interface names and resetting the interface version. 84 Once the protocol is to be declared stable, the 'z' prefix and the 85 version number in the protocol and interface names are removed and the 86 interface version number is reset. 87 </description> 88 89 <request name="destroy" type="destructor"> 90 <description summary="unbind the factory"> 91 Objects created through this interface, especially wl_buffers, will 92 remain valid. 93 </description> 94 </request> 95 96 <request name="create_params"> 97 <description summary="create a temporary object for buffer parameters"> 98 This temporary object is used to collect multiple dmabuf handles into 99 a single batch to create a wl_buffer. It can only be used once and 100 should be destroyed after a 'created' or 'failed' event has been 101 received. 102 </description> 103 <arg name="params_id" type="new_id" interface="zwp_linux_buffer_params_v1" 104 summary="the new temporary"/> 105 </request> 106 107 <event name="format"> 108 <description summary="supported buffer format"> 109 This event advertises one buffer format that the server supports. 110 All the supported formats are advertised once when the client 111 binds to this interface. A roundtrip after binding guarantees 112 that the client has received all supported formats. 113 114 For the definition of the format codes, see the 115 zwp_linux_buffer_params_v1::create request. 116 117 Warning: the 'format' event is likely to be deprecated and replaced 118 with the 'modifier' event introduced in zwp_linux_dmabuf_v1 119 version 3, described below. Please refrain from using the information 120 received from this event. 121 </description> 122 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 123 </event> 124 125 <event name="modifier" since="3"> 126 <description summary="supported buffer format modifier"> 127 This event advertises the formats that the server supports, along with 128 the modifiers supported for each format. All the supported modifiers 129 for all the supported formats are advertised once when the client 130 binds to this interface. A roundtrip after binding guarantees that 131 the client has received all supported format-modifier pairs. 132 133 For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi == 134 0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event. 135 It indicates that the server can support the format with an implicit 136 modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it 137 is as if no explicit modifier is specified. The effective modifier 138 will be derived from the dmabuf. 139 140 For the definition of the format and modifier codes, see the 141 zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add 142 requests. 143 </description> 144 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 145 <arg name="modifier_hi" type="uint" 146 summary="high 32 bits of layout modifier"/> 147 <arg name="modifier_lo" type="uint" 148 summary="low 32 bits of layout modifier"/> 149 </event> 150 </interface> 151 152 <interface name="zwp_linux_buffer_params_v1" version="3"> 153 <description summary="parameters for creating a dmabuf-based wl_buffer"> 154 This temporary object is a collection of dmabufs and other 155 parameters that together form a single logical buffer. The temporary 156 object may eventually create one wl_buffer unless cancelled by 157 destroying it before requesting 'create'. 158 159 Single-planar formats only require one dmabuf, however 160 multi-planar formats may require more than one dmabuf. For all 161 formats, an 'add' request must be called once per plane (even if the 162 underlying dmabuf fd is identical). 163 164 You must use consecutive plane indices ('plane_idx' argument for 'add') 165 from zero to the number of planes used by the drm_fourcc format code. 166 All planes required by the format must be given exactly once, but can 167 be given in any order. Each plane index can be set only once. 168 </description> 169 170 <enum name="error"> 171 <entry name="already_used" value="0" 172 summary="the dmabuf_batch object has already been used to create a wl_buffer"/> 173 <entry name="plane_idx" value="1" 174 summary="plane index out of bounds"/> 175 <entry name="plane_set" value="2" 176 summary="the plane index was already set"/> 177 <entry name="incomplete" value="3" 178 summary="missing or too many planes to create a buffer"/> 179 <entry name="invalid_format" value="4" 180 summary="format not supported"/> 181 <entry name="invalid_dimensions" value="5" 182 summary="invalid width or height"/> 183 <entry name="out_of_bounds" value="6" 184 summary="offset + stride * height goes out of dmabuf bounds"/> 185 <entry name="invalid_wl_buffer" value="7" 186 summary="invalid wl_buffer resulted from importing dmabufs via 187 the create_immed request on given buffer_params"/> 188 </enum> 189 190 <request name="destroy" type="destructor"> 191 <description summary="delete this object, used or not"> 192 Cleans up the temporary data sent to the server for dmabuf-based 193 wl_buffer creation. 194 </description> 195 </request> 196 197 <request name="add"> 198 <description summary="add a dmabuf to the temporary set"> 199 This request adds one dmabuf to the set in this 200 zwp_linux_buffer_params_v1. 201 202 The 64-bit unsigned value combined from modifier_hi and modifier_lo 203 is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the 204 fb modifier, which is defined in drm_mode.h of Linux UAPI. 205 This is an opaque token. Drivers use this token to express tiling, 206 compression, etc. driver-specific modifications to the base format 207 defined by the DRM fourcc code. 208 209 Warning: It should be an error if the format/modifier pair was not 210 advertised with the modifier event. This is not enforced yet because 211 some implementations always accept DRM_FORMAT_MOD_INVALID. Also 212 version 2 of this protocol does not have the modifier event. 213 214 This request raises the PLANE_IDX error if plane_idx is too large. 215 The error PLANE_SET is raised if attempting to set a plane that 216 was already set. 217 </description> 218 <arg name="fd" type="fd" summary="dmabuf fd"/> 219 <arg name="plane_idx" type="uint" summary="plane index"/> 220 <arg name="offset" type="uint" summary="offset in bytes"/> 221 <arg name="stride" type="uint" summary="stride in bytes"/> 222 <arg name="modifier_hi" type="uint" 223 summary="high 32 bits of layout modifier"/> 224 <arg name="modifier_lo" type="uint" 225 summary="low 32 bits of layout modifier"/> 226 </request> 227 228 <request name="add_buffer_handle"> 229 <description summary="set bufferhandle info"> 230 </description> 231 <arg name="fd" type="int" summary="bufferhandle fd"/> 232 <arg name="width" type="int" summary="bufferhandle width"/> 233 <arg name="stride" type="int" summary="bufferhandle stride"/> 234 <arg name="height" type="int" summary="bufferhandle height"/> 235 <arg name="size" type="int" summary="bufferhandle size"/> 236 <arg name="format" type="int" summary="bufferhandle format"/> 237 <arg name="usage_hi" type="uint" 238 summary="high 32 bits of bufferhandle usage"/> 239 <arg name="usage_lo" type="uint" 240 summary="low 32 bits of bufferhandle usage"/> 241 <arg name="phyaddr_hi" type="uint" 242 summary="high 32 bits of bufferhandle phyaddr"/> 243 <arg name="phyaddr_lo" type="uint" 244 summary="low 32 bits of bufferhandle phyaddr"/> 245 <arg name="key" type="int" summary="bufferhandle key"/> 246 <arg name="reservefds" type="array" summary="bufferhandle reservefds"/> 247 <arg name="reserveints" type="array" summary="bufferhandle reserveints"/> 248 </request> 249 250 <enum name="flags"> 251 <entry name="y_invert" value="1" summary="contents are y-inverted"/> 252 <entry name="interlaced" value="2" summary="content is interlaced"/> 253 <entry name="bottom_first" value="4" summary="bottom field first"/> 254 </enum> 255 256 <request name="create"> 257 <description summary="create a wl_buffer from the given dmabufs"> 258 This asks for creation of a wl_buffer from the added dmabuf 259 buffers. The wl_buffer is not created immediately but returned via 260 the 'created' event if the dmabuf sharing succeeds. The sharing 261 may fail at runtime for reasons a client cannot predict, in 262 which case the 'failed' event is triggered. 263 264 The 'format' argument is a DRM_FORMAT code, as defined by the 265 libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the 266 authoritative source on how the format codes should work. 267 268 The 'flags' is a bitfield of the flags defined in enum "flags". 269 'y_invert' means the that the image needs to be y-flipped. 270 271 Flag 'interlaced' means that the frame in the buffer is not 272 progressive as usual, but interlaced. An interlaced buffer as 273 supported here must always contain both top and bottom fields. 274 The top field always begins on the first pixel row. The temporal 275 ordering between the two fields is top field first, unless 276 'bottom_first' is specified. It is undefined whether 'bottom_first' 277 is ignored if 'interlaced' is not set. 278 279 This protocol does not convey any information about field rate, 280 duration, or timing, other than the relative ordering between the 281 two fields in one buffer. A compositor may have to estimate the 282 intended field rate from the incoming buffer rate. It is undefined 283 whether the time of receiving wl_surface.commit with a new buffer 284 attached, applying the wl_surface state, wl_surface.frame callback 285 trigger, presentation, or any other point in the compositor cycle 286 is used to measure the frame or field times. There is no support 287 for detecting missed or late frames/fields/buffers either, and 288 there is no support whatsoever for cooperating with interlaced 289 compositor output. 290 291 The composited image quality resulting from the use of interlaced 292 buffers is explicitly undefined. A compositor may use elaborate 293 hardware features or software to deinterlace and create progressive 294 output frames from a sequence of interlaced input buffers, or it 295 may produce substandard image quality. However, compositors that 296 cannot guarantee reasonable image quality in all cases are recommended 297 to just reject all interlaced buffers. 298 299 Any argument errors, including non-positive width or height, 300 mismatch between the number of planes and the format, bad 301 format, bad offset or stride, may be indicated by fatal protocol 302 errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, 303 OUT_OF_BOUNDS. 304 305 Dmabuf import errors in the server that are not obvious client 306 bugs are returned via the 'failed' event as non-fatal. This 307 allows attempting dmabuf sharing and falling back in the client 308 if it fails. 309 310 This request can be sent only once in the object's lifetime, after 311 which the only legal request is destroy. This object should be 312 destroyed after issuing a 'create' request. Attempting to use this 313 object after issuing 'create' raises ALREADY_USED protocol error. 314 315 It is not mandatory to issue 'create'. If a client wants to 316 cancel the buffer creation, it can just destroy this object. 317 </description> 318 <arg name="width" type="int" summary="base plane width in pixels"/> 319 <arg name="height" type="int" summary="base plane height in pixels"/> 320 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 321 <arg name="flags" type="uint" summary="see enum flags"/> 322 </request> 323 324 <event name="created"> 325 <description summary="buffer creation succeeded"> 326 This event indicates that the attempted buffer creation was 327 successful. It provides the new wl_buffer referencing the dmabuf(s). 328 329 Upon receiving this event, the client should destroy the 330 zlinux_dmabuf_params object. 331 </description> 332 <arg name="buffer" type="new_id" interface="wl_buffer" 333 summary="the newly created wl_buffer"/> 334 </event> 335 336 <event name="failed"> 337 <description summary="buffer creation failed"> 338 This event indicates that the attempted buffer creation has 339 failed. It usually means that one of the dmabuf constraints 340 has not been fulfilled. 341 342 Upon receiving this event, the client should destroy the 343 zlinux_buffer_params object. 344 </description> 345 </event> 346 347 <request name="create_immed" since="2"> 348 <description summary="immediately create a wl_buffer from the given 349 dmabufs"> 350 This asks for immediate creation of a wl_buffer by importing the 351 added dmabufs. 352 353 In case of import success, no event is sent from the server, and the 354 wl_buffer is ready to be used by the client. 355 356 Upon import failure, either of the following may happen, as seen fit 357 by the implementation: 358 - the client is terminated with one of the following fatal protocol 359 errors: 360 - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS, 361 in case of argument errors such as mismatch between the number 362 of planes and the format, bad format, non-positive width or 363 height, or bad offset or stride. 364 - INVALID_WL_BUFFER, in case the cause for failure is unknown or 365 plaform specific. 366 - the server creates an invalid wl_buffer, marks it as failed and 367 sends a 'failed' event to the client. The result of using this 368 invalid wl_buffer as an argument in any request by the client is 369 defined by the compositor implementation. 370 371 This takes the same arguments as a 'create' request, and obeys the 372 same restrictions. 373 </description> 374 <arg name="buffer_id" type="new_id" interface="wl_buffer" 375 summary="id for the newly created wl_buffer"/> 376 <arg name="width" type="int" summary="base plane width in pixels"/> 377 <arg name="height" type="int" summary="base plane height in pixels"/> 378 <arg name="format" type="uint" summary="DRM_FORMAT code"/> 379 <arg name="flags" type="uint" summary="see enum flags"/> 380 </request> 381 382 </interface> 383 384</protocol> 385