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