1*504245a5SDaniel Stone.. SPDX-License-Identifier: GPL-2.0 2*504245a5SDaniel Stone.. Copyright 2021-2023 Collabora Ltd. 3*504245a5SDaniel Stone 4*504245a5SDaniel Stone======================== 5*504245a5SDaniel StoneExchanging pixel buffers 6*504245a5SDaniel Stone======================== 7*504245a5SDaniel Stone 8*504245a5SDaniel StoneAs originally designed, the Linux graphics subsystem had extremely limited 9*504245a5SDaniel Stonesupport for sharing pixel-buffer allocations between processes, devices, and 10*504245a5SDaniel Stonesubsystems. Modern systems require extensive integration between all three 11*504245a5SDaniel Stoneclasses; this document details how applications and kernel subsystems should 12*504245a5SDaniel Stoneapproach this sharing for two-dimensional image data. 13*504245a5SDaniel Stone 14*504245a5SDaniel StoneIt is written with reference to the DRM subsystem for GPU and display devices, 15*504245a5SDaniel StoneV4L2 for media devices, and also to Vulkan, EGL and Wayland, for userspace 16*504245a5SDaniel Stonesupport, however any other subsystems should also follow this design and advice. 17*504245a5SDaniel Stone 18*504245a5SDaniel Stone 19*504245a5SDaniel StoneGlossary of terms 20*504245a5SDaniel Stone================= 21*504245a5SDaniel Stone 22*504245a5SDaniel Stone.. glossary:: 23*504245a5SDaniel Stone 24*504245a5SDaniel Stone image: 25*504245a5SDaniel Stone Conceptually a two-dimensional array of pixels. The pixels may be stored 26*504245a5SDaniel Stone in one or more memory buffers. Has width and height in pixels, pixel 27*504245a5SDaniel Stone format and modifier (implicit or explicit). 28*504245a5SDaniel Stone 29*504245a5SDaniel Stone row: 30*504245a5SDaniel Stone A span along a single y-axis value, e.g. from co-ordinates (0,100) to 31*504245a5SDaniel Stone (200,100). 32*504245a5SDaniel Stone 33*504245a5SDaniel Stone scanline: 34*504245a5SDaniel Stone Synonym for row. 35*504245a5SDaniel Stone 36*504245a5SDaniel Stone column: 37*504245a5SDaniel Stone A span along a single x-axis value, e.g. from co-ordinates (100,0) to 38*504245a5SDaniel Stone (100,100). 39*504245a5SDaniel Stone 40*504245a5SDaniel Stone memory buffer: 41*504245a5SDaniel Stone A piece of memory for storing (parts of) pixel data. Has stride and size 42*504245a5SDaniel Stone in bytes and at least one handle in some API. May contain one or more 43*504245a5SDaniel Stone planes. 44*504245a5SDaniel Stone 45*504245a5SDaniel Stone plane: 46*504245a5SDaniel Stone A two-dimensional array of some or all of an image's color and alpha 47*504245a5SDaniel Stone channel values. 48*504245a5SDaniel Stone 49*504245a5SDaniel Stone pixel: 50*504245a5SDaniel Stone A picture element. Has a single color value which is defined by one or 51*504245a5SDaniel Stone more color channels values, e.g. R, G and B, or Y, Cb and Cr. May also 52*504245a5SDaniel Stone have an alpha value as an additional channel. 53*504245a5SDaniel Stone 54*504245a5SDaniel Stone pixel data: 55*504245a5SDaniel Stone Bytes or bits that represent some or all of the color/alpha channel values 56*504245a5SDaniel Stone of a pixel or an image. The data for one pixel may be spread over several 57*504245a5SDaniel Stone planes or memory buffers depending on format and modifier. 58*504245a5SDaniel Stone 59*504245a5SDaniel Stone color value: 60*504245a5SDaniel Stone A tuple of numbers, representing a color. Each element in the tuple is a 61*504245a5SDaniel Stone color channel value. 62*504245a5SDaniel Stone 63*504245a5SDaniel Stone color channel: 64*504245a5SDaniel Stone One of the dimensions in a color model. For example, RGB model has 65*504245a5SDaniel Stone channels R, G, and B. Alpha channel is sometimes counted as a color 66*504245a5SDaniel Stone channel as well. 67*504245a5SDaniel Stone 68*504245a5SDaniel Stone pixel format: 69*504245a5SDaniel Stone A description of how pixel data represents the pixel's color and alpha 70*504245a5SDaniel Stone values. 71*504245a5SDaniel Stone 72*504245a5SDaniel Stone modifier: 73*504245a5SDaniel Stone A description of how pixel data is laid out in memory buffers. 74*504245a5SDaniel Stone 75*504245a5SDaniel Stone alpha: 76*504245a5SDaniel Stone A value that denotes the color coverage in a pixel. Sometimes used for 77*504245a5SDaniel Stone translucency instead. 78*504245a5SDaniel Stone 79*504245a5SDaniel Stone stride: 80*504245a5SDaniel Stone A value that denotes the relationship between pixel-location co-ordinates 81*504245a5SDaniel Stone and byte-offset values. Typically used as the byte offset between two 82*504245a5SDaniel Stone pixels at the start of vertically-consecutive tiling blocks. For linear 83*504245a5SDaniel Stone layouts, the byte offset between two vertically-adjacent pixels. For 84*504245a5SDaniel Stone non-linear formats the stride must be computed in a consistent way, which 85*504245a5SDaniel Stone usually is done as-if the layout was linear. 86*504245a5SDaniel Stone 87*504245a5SDaniel Stone pitch: 88*504245a5SDaniel Stone Synonym for stride. 89*504245a5SDaniel Stone 90*504245a5SDaniel Stone 91*504245a5SDaniel StoneFormats and modifiers 92*504245a5SDaniel Stone===================== 93*504245a5SDaniel Stone 94*504245a5SDaniel StoneEach buffer must have an underlying format. This format describes the color 95*504245a5SDaniel Stonevalues provided for each pixel. Although each subsystem has its own format 96*504245a5SDaniel Stonedescriptions (e.g. V4L2 and fbdev), the ``DRM_FORMAT_*`` tokens should be reused 97*504245a5SDaniel Stonewherever possible, as they are the standard descriptions used for interchange. 98*504245a5SDaniel StoneThese tokens are described in the ``drm_fourcc.h`` file, which is a part of 99*504245a5SDaniel StoneDRM's uAPI. 100*504245a5SDaniel Stone 101*504245a5SDaniel StoneEach ``DRM_FORMAT_*`` token describes the translation between a pixel 102*504245a5SDaniel Stoneco-ordinate in an image, and the color values for that pixel contained within 103*504245a5SDaniel Stoneits memory buffers. The number and type of color channels are described: 104*504245a5SDaniel Stonewhether they are RGB or YUV, integer or floating-point, the size of each channel 105*504245a5SDaniel Stoneand their locations within the pixel memory, and the relationship between color 106*504245a5SDaniel Stoneplanes. 107*504245a5SDaniel Stone 108*504245a5SDaniel StoneFor example, ``DRM_FORMAT_ARGB8888`` describes a format in which each pixel has 109*504245a5SDaniel Stonea single 32-bit value in memory. Alpha, red, green, and blue, color channels are 110*504245a5SDaniel Stoneavailable at 8-bit precision per channel, ordered respectively from most to 111*504245a5SDaniel Stoneleast significant bits in little-endian storage. ``DRM_FORMAT_*`` is not 112*504245a5SDaniel Stoneaffected by either CPU or device endianness; the byte pattern in memory is 113*504245a5SDaniel Stonealways as described in the format definition, which is usually little-endian. 114*504245a5SDaniel Stone 115*504245a5SDaniel StoneAs a more complex example, ``DRM_FORMAT_NV12`` describes a format in which luma 116*504245a5SDaniel Stoneand chroma YUV samples are stored in separate planes, where the chroma plane is 117*504245a5SDaniel Stonestored at half the resolution in both dimensions (i.e. one U/V chroma 118*504245a5SDaniel Stonesample is stored for each 2x2 pixel grouping). 119*504245a5SDaniel Stone 120*504245a5SDaniel StoneFormat modifiers describe a translation mechanism between these per-pixel memory 121*504245a5SDaniel Stonesamples, and the actual memory storage for the buffer. The most straightforward 122*504245a5SDaniel Stonemodifier is ``DRM_FORMAT_MOD_LINEAR``, describing a scheme in which each plane 123*504245a5SDaniel Stoneis laid out row-sequentially, from the top-left to the bottom-right corner. 124*504245a5SDaniel StoneThis is considered the baseline interchange format, and most convenient for CPU 125*504245a5SDaniel Stoneaccess. 126*504245a5SDaniel Stone 127*504245a5SDaniel StoneModern hardware employs much more sophisticated access mechanisms, typically 128*504245a5SDaniel Stonemaking use of tiled access and possibly also compression. For example, the 129*504245a5SDaniel Stone``DRM_FORMAT_MOD_VIVANTE_TILED`` modifier describes memory storage where pixels 130*504245a5SDaniel Stoneare stored in 4x4 blocks arranged in row-major ordering, i.e. the first tile in 131*504245a5SDaniel Stonea plane stores pixels (0,0) to (3,3) inclusive, and the second tile in a plane 132*504245a5SDaniel Stonestores pixels (4,0) to (7,3) inclusive. 133*504245a5SDaniel Stone 134*504245a5SDaniel StoneSome modifiers may modify the number of planes required for an image; for 135*504245a5SDaniel Stoneexample, the ``I915_FORMAT_MOD_Y_TILED_CCS`` modifier adds a second plane to RGB 136*504245a5SDaniel Stoneformats in which it stores data about the status of every tile, notably 137*504245a5SDaniel Stoneincluding whether the tile is fully populated with pixel data, or can be 138*504245a5SDaniel Stoneexpanded from a single solid color. 139*504245a5SDaniel Stone 140*504245a5SDaniel StoneThese extended layouts are highly vendor-specific, and even specific to 141*504245a5SDaniel Stoneparticular generations or configurations of devices per-vendor. For this reason, 142*504245a5SDaniel Stonesupport of modifiers must be explicitly enumerated and negotiated by all users 143*504245a5SDaniel Stonein order to ensure a compatible and optimal pipeline, as discussed below. 144*504245a5SDaniel Stone 145*504245a5SDaniel Stone 146*504245a5SDaniel StoneDimensions and size 147*504245a5SDaniel Stone=================== 148*504245a5SDaniel Stone 149*504245a5SDaniel StoneEach pixel buffer must be accompanied by logical pixel dimensions. This refers 150*504245a5SDaniel Stoneto the number of unique samples which can be extracted from, or stored to, the 151*504245a5SDaniel Stoneunderlying memory storage. For example, even though a 1920x1080 152*504245a5SDaniel Stone``DRM_FORMAT_NV12`` buffer has a luma plane containing 1920x1080 samples for the Y 153*504245a5SDaniel Stonecomponent, and 960x540 samples for the U and V components, the overall buffer is 154*504245a5SDaniel Stonestill described as having dimensions of 1920x1080. 155*504245a5SDaniel Stone 156*504245a5SDaniel StoneThe in-memory storage of a buffer is not guaranteed to begin immediately at the 157*504245a5SDaniel Stonebase address of the underlying memory, nor is it guaranteed that the memory 158*504245a5SDaniel Stonestorage is tightly clipped to either dimension. 159*504245a5SDaniel Stone 160*504245a5SDaniel StoneEach plane must therefore be described with an ``offset`` in bytes, which will be 161*504245a5SDaniel Stoneadded to the base address of the memory storage before performing any per-pixel 162*504245a5SDaniel Stonecalculations. This may be used to combine multiple planes into a single memory 163*504245a5SDaniel Stonebuffer; for example, ``DRM_FORMAT_NV12`` may be stored in a single memory buffer 164*504245a5SDaniel Stonewhere the luma plane's storage begins immediately at the start of the buffer 165*504245a5SDaniel Stonewith an offset of 0, and the chroma plane's storage follows within the same buffer 166*504245a5SDaniel Stonebeginning from the byte offset for that plane. 167*504245a5SDaniel Stone 168*504245a5SDaniel StoneEach plane must also have a ``stride`` in bytes, expressing the offset in memory 169*504245a5SDaniel Stonebetween two contiguous row. For example, a ``DRM_FORMAT_MOD_LINEAR`` buffer 170*504245a5SDaniel Stonewith dimensions of 1000x1000 may have been allocated as if it were 1024x1000, in 171*504245a5SDaniel Stoneorder to allow for aligned access patterns. In this case, the buffer will still 172*504245a5SDaniel Stonebe described with a width of 1000, however the stride will be ``1024 * bpp``, 173*504245a5SDaniel Stoneindicating that there are 24 pixels at the positive extreme of the x axis whose 174*504245a5SDaniel Stonevalues are not significant. 175*504245a5SDaniel Stone 176*504245a5SDaniel StoneBuffers may also be padded further in the y dimension, simply by allocating a 177*504245a5SDaniel Stonelarger area than would ordinarily be required. For example, many media decoders 178*504245a5SDaniel Stoneare not able to natively output buffers of height 1080, but instead require an 179*504245a5SDaniel Stoneeffective height of 1088 pixels. In this case, the buffer continues to be 180*504245a5SDaniel Stonedescribed as having a height of 1080, with the memory allocation for each buffer 181*504245a5SDaniel Stonebeing increased to account for the extra padding. 182*504245a5SDaniel Stone 183*504245a5SDaniel Stone 184*504245a5SDaniel StoneEnumeration 185*504245a5SDaniel Stone=========== 186*504245a5SDaniel Stone 187*504245a5SDaniel StoneEvery user of pixel buffers must be able to enumerate a set of supported formats 188*504245a5SDaniel Stoneand modifiers, described together. Within KMS, this is achieved with the 189*504245a5SDaniel Stone``IN_FORMATS`` property on each DRM plane, listing the supported DRM formats, and 190*504245a5SDaniel Stonethe modifiers supported for each format. In userspace, this is supported through 191*504245a5SDaniel Stonethe `EGL_EXT_image_dma_buf_import_modifiers`_ extension entrypoints for EGL, the 192*504245a5SDaniel Stone`VK_EXT_image_drm_format_modifier`_ extension for Vulkan, and the 193*504245a5SDaniel Stone`zwp_linux_dmabuf_v1`_ extension for Wayland. 194*504245a5SDaniel Stone 195*504245a5SDaniel StoneEach of these interfaces allows users to query a set of supported 196*504245a5SDaniel Stoneformat+modifier combinations. 197*504245a5SDaniel Stone 198*504245a5SDaniel Stone 199*504245a5SDaniel StoneNegotiation 200*504245a5SDaniel Stone=========== 201*504245a5SDaniel Stone 202*504245a5SDaniel StoneIt is the responsibility of userspace to negotiate an acceptable format+modifier 203*504245a5SDaniel Stonecombination for its usage. This is performed through a simple intersection of 204*504245a5SDaniel Stonelists. For example, if a user wants to use Vulkan to render an image to be 205*504245a5SDaniel Stonedisplayed on a KMS plane, it must: 206*504245a5SDaniel Stone 207*504245a5SDaniel Stone - query KMS for the ``IN_FORMATS`` property for the given plane 208*504245a5SDaniel Stone - query Vulkan for the supported formats for its physical device, making sure 209*504245a5SDaniel Stone to pass the ``VkImageUsageFlagBits`` and ``VkImageCreateFlagBits`` 210*504245a5SDaniel Stone corresponding to the intended rendering use 211*504245a5SDaniel Stone - intersect these formats to determine the most appropriate one 212*504245a5SDaniel Stone - for this format, intersect the lists of supported modifiers for both KMS and 213*504245a5SDaniel Stone Vulkan, to obtain a final list of acceptable modifiers for that format 214*504245a5SDaniel Stone 215*504245a5SDaniel StoneThis intersection must be performed for all usages. For example, if the user 216*504245a5SDaniel Stonealso wishes to encode the image to a video stream, it must query the media API 217*504245a5SDaniel Stoneit intends to use for encoding for the set of modifiers it supports, and 218*504245a5SDaniel Stoneadditionally intersect against this list. 219*504245a5SDaniel Stone 220*504245a5SDaniel StoneIf the intersection of all lists is an empty list, it is not possible to share 221*504245a5SDaniel Stonebuffers in this way, and an alternate strategy must be considered (e.g. using 222*504245a5SDaniel StoneCPU access routines to copy data between the different uses, with the 223*504245a5SDaniel Stonecorresponding performance cost). 224*504245a5SDaniel Stone 225*504245a5SDaniel StoneThe resulting modifier list is unsorted; the order is not significant. 226*504245a5SDaniel Stone 227*504245a5SDaniel Stone 228*504245a5SDaniel StoneAllocation 229*504245a5SDaniel Stone========== 230*504245a5SDaniel Stone 231*504245a5SDaniel StoneOnce userspace has determined an appropriate format, and corresponding list of 232*504245a5SDaniel Stoneacceptable modifiers, it must allocate the buffer. As there is no universal 233*504245a5SDaniel Stonebuffer-allocation interface available at either kernel or userspace level, the 234*504245a5SDaniel Stoneclient makes an arbitrary choice of allocation interface such as Vulkan, GBM, or 235*504245a5SDaniel Stonea media API. 236*504245a5SDaniel Stone 237*504245a5SDaniel StoneEach allocation request must take, at a minimum: the pixel format, a list of 238*504245a5SDaniel Stoneacceptable modifiers, and the buffer's width and height. Each API may extend 239*504245a5SDaniel Stonethis set of properties in different ways, such as allowing allocation in more 240*504245a5SDaniel Stonethan two dimensions, intended usage patterns, etc. 241*504245a5SDaniel Stone 242*504245a5SDaniel StoneThe component which allocates the buffer will make an arbitrary choice of what 243*504245a5SDaniel Stoneit considers the 'best' modifier within the acceptable list for the requested 244*504245a5SDaniel Stoneallocation, any padding required, and further properties of the underlying 245*504245a5SDaniel Stonememory buffers such as whether they are stored in system or device-specific 246*504245a5SDaniel Stonememory, whether or not they are physically contiguous, and their cache mode. 247*504245a5SDaniel StoneThese properties of the memory buffer are not visible to userspace, however the 248*504245a5SDaniel Stone``dma-heaps`` API is an effort to address this. 249*504245a5SDaniel Stone 250*504245a5SDaniel StoneAfter allocation, the client must query the allocator to determine the actual 251*504245a5SDaniel Stonemodifier selected for the buffer, as well as the per-plane offset and stride. 252*504245a5SDaniel StoneAllocators are not permitted to vary the format in use, to select a modifier not 253*504245a5SDaniel Stoneprovided within the acceptable list, nor to vary the pixel dimensions other than 254*504245a5SDaniel Stonethe padding expressed through offset, stride, and size. 255*504245a5SDaniel Stone 256*504245a5SDaniel StoneCommunicating additional constraints, such as alignment of stride or offset, 257*504245a5SDaniel Stoneplacement within a particular memory area, etc, is out of scope of dma-buf, 258*504245a5SDaniel Stoneand is not solved by format and modifier tokens. 259*504245a5SDaniel Stone 260*504245a5SDaniel Stone 261*504245a5SDaniel StoneImport 262*504245a5SDaniel Stone====== 263*504245a5SDaniel Stone 264*504245a5SDaniel StoneTo use a buffer within a different context, device, or subsystem, the user 265*504245a5SDaniel Stonepasses these parameters (format, modifier, width, height, and per-plane offset 266*504245a5SDaniel Stoneand stride) to an importing API. 267*504245a5SDaniel Stone 268*504245a5SDaniel StoneEach memory buffer is referred to by a buffer handle, which may be unique or 269*504245a5SDaniel Stoneduplicated within an image. For example, a ``DRM_FORMAT_NV12`` buffer may have 270*504245a5SDaniel Stonethe luma and chroma buffers combined into a single memory buffer by use of the 271*504245a5SDaniel Stoneper-plane offset parameters, or they may be completely separate allocations in 272*504245a5SDaniel Stonememory. For this reason, each import and allocation API must provide a separate 273*504245a5SDaniel Stonehandle for each plane. 274*504245a5SDaniel Stone 275*504245a5SDaniel StoneEach kernel subsystem has its own types and interfaces for buffer management. 276*504245a5SDaniel StoneDRM uses GEM buffer objects (BOs), V4L2 has its own references, etc. These types 277*504245a5SDaniel Stoneare not portable between contexts, processes, devices, or subsystems. 278*504245a5SDaniel Stone 279*504245a5SDaniel StoneTo address this, ``dma-buf`` handles are used as the universal interchange for 280*504245a5SDaniel Stonebuffers. Subsystem-specific operations are used to export native buffer handles 281*504245a5SDaniel Stoneto a ``dma-buf`` file descriptor, and to import those file descriptors into a 282*504245a5SDaniel Stonenative buffer handle. dma-buf file descriptors can be transferred between 283*504245a5SDaniel Stonecontexts, processes, devices, and subsystems. 284*504245a5SDaniel Stone 285*504245a5SDaniel StoneFor example, a Wayland media player may use V4L2 to decode a video frame into a 286*504245a5SDaniel Stone``DRM_FORMAT_NV12`` buffer. This will result in two memory planes (luma and 287*504245a5SDaniel Stonechroma) being dequeued by the user from V4L2. These planes are then exported to 288*504245a5SDaniel Stoneone dma-buf file descriptor per plane, these descriptors are then sent along 289*504245a5SDaniel Stonewith the metadata (format, modifier, width, height, per-plane offset and stride) 290*504245a5SDaniel Stoneto the Wayland server. The Wayland server will then import these file 291*504245a5SDaniel Stonedescriptors as an EGLImage for use through EGL/OpenGL (ES), a VkImage for use 292*504245a5SDaniel Stonethrough Vulkan, or a KMS framebuffer object; each of these import operations 293*504245a5SDaniel Stonewill take the same metadata and convert the dma-buf file descriptors into their 294*504245a5SDaniel Stonenative buffer handles. 295*504245a5SDaniel Stone 296*504245a5SDaniel StoneHaving a non-empty intersection of supported modifiers does not guarantee that 297*504245a5SDaniel Stoneimport will succeed into all consumers; they may have constraints beyond those 298*504245a5SDaniel Stoneimplied by modifiers which must be satisfied. 299*504245a5SDaniel Stone 300*504245a5SDaniel Stone 301*504245a5SDaniel StoneImplicit modifiers 302*504245a5SDaniel Stone================== 303*504245a5SDaniel Stone 304*504245a5SDaniel StoneThe concept of modifiers post-dates all of the subsystems mentioned above. As 305*504245a5SDaniel Stonesuch, it has been retrofitted into all of these APIs, and in order to ensure 306*504245a5SDaniel Stonebackwards compatibility, support is needed for drivers and userspace which do 307*504245a5SDaniel Stonenot (yet) support modifiers. 308*504245a5SDaniel Stone 309*504245a5SDaniel StoneAs an example, GBM is used to allocate buffers to be shared between EGL for 310*504245a5SDaniel Stonerendering and KMS for display. It has two entrypoints for allocating buffers: 311*504245a5SDaniel Stone``gbm_bo_create`` which only takes the format, width, height, and a usage token, 312*504245a5SDaniel Stoneand ``gbm_bo_create_with_modifiers`` which extends this with a list of modifiers. 313*504245a5SDaniel Stone 314*504245a5SDaniel StoneIn the latter case, the allocation is as discussed above, being provided with a 315*504245a5SDaniel Stonelist of acceptable modifiers that the implementation can choose from (or fail if 316*504245a5SDaniel Stoneit is not possible to allocate within those constraints). In the former case 317*504245a5SDaniel Stonewhere modifiers are not provided, the GBM implementation must make its own 318*504245a5SDaniel Stonechoice as to what is likely to be the 'best' layout. Such a choice is entirely 319*504245a5SDaniel Stoneimplementation-specific: some will internally use tiled layouts which are not 320*504245a5SDaniel StoneCPU-accessible if the implementation decides that is a good idea through 321*504245a5SDaniel Stonewhatever heuristic. It is the implementation's responsibility to ensure that 322*504245a5SDaniel Stonethis choice is appropriate. 323*504245a5SDaniel Stone 324*504245a5SDaniel StoneTo support this case where the layout is not known because there is no awareness 325*504245a5SDaniel Stoneof modifiers, a special ``DRM_FORMAT_MOD_INVALID`` token has been defined. This 326*504245a5SDaniel Stonepseudo-modifier declares that the layout is not known, and that the driver 327*504245a5SDaniel Stoneshould use its own logic to determine what the underlying layout may be. 328*504245a5SDaniel Stone 329*504245a5SDaniel Stone.. note:: 330*504245a5SDaniel Stone 331*504245a5SDaniel Stone ``DRM_FORMAT_MOD_INVALID`` is a non-zero value. The modifier value zero is 332*504245a5SDaniel Stone ``DRM_FORMAT_MOD_LINEAR``, which is an explicit guarantee that the image 333*504245a5SDaniel Stone has the linear layout. Care and attention should be taken to ensure that 334*504245a5SDaniel Stone zero as a default value is not mixed up with either no modifier or the linear 335*504245a5SDaniel Stone modifier. Also note that in some APIs the invalid modifier value is specified 336*504245a5SDaniel Stone with an out-of-band flag, like in ``DRM_IOCTL_MODE_ADDFB2``. 337*504245a5SDaniel Stone 338*504245a5SDaniel StoneThere are four cases where this token may be used: 339*504245a5SDaniel Stone - during enumeration, an interface may return ``DRM_FORMAT_MOD_INVALID``, either 340*504245a5SDaniel Stone as the sole member of a modifier list to declare that explicit modifiers are 341*504245a5SDaniel Stone not supported, or as part of a larger list to declare that implicit modifiers 342*504245a5SDaniel Stone may be used 343*504245a5SDaniel Stone - during allocation, a user may supply ``DRM_FORMAT_MOD_INVALID``, either as the 344*504245a5SDaniel Stone sole member of a modifier list (equivalent to not supplying a modifier list 345*504245a5SDaniel Stone at all) to declare that explicit modifiers are not supported and must not be 346*504245a5SDaniel Stone used, or as part of a larger list to declare that an allocation using implicit 347*504245a5SDaniel Stone modifiers is acceptable 348*504245a5SDaniel Stone - in a post-allocation query, an implementation may return 349*504245a5SDaniel Stone ``DRM_FORMAT_MOD_INVALID`` as the modifier of the allocated buffer to declare 350*504245a5SDaniel Stone that the underlying layout is implementation-defined and that an explicit 351*504245a5SDaniel Stone modifier description is not available; per the above rules, this may only be 352*504245a5SDaniel Stone returned when the user has included ``DRM_FORMAT_MOD_INVALID`` as part of the 353*504245a5SDaniel Stone list of acceptable modifiers, or not provided a list 354*504245a5SDaniel Stone - when importing a buffer, the user may supply ``DRM_FORMAT_MOD_INVALID`` as the 355*504245a5SDaniel Stone buffer modifier (or not supply a modifier) to indicate that the modifier is 356*504245a5SDaniel Stone unknown for whatever reason; this is only acceptable when the buffer has 357*504245a5SDaniel Stone not been allocated with an explicit modifier 358*504245a5SDaniel Stone 359*504245a5SDaniel StoneIt follows from this that for any single buffer, the complete chain of operations 360*504245a5SDaniel Stoneformed by the producer and all the consumers must be either fully implicit or fully 361*504245a5SDaniel Stoneexplicit. For example, if a user wishes to allocate a buffer for use between 362*504245a5SDaniel StoneGPU, display, and media, but the media API does not support modifiers, then the 363*504245a5SDaniel Stoneuser **must not** allocate the buffer with explicit modifiers and attempt to 364*504245a5SDaniel Stoneimport the buffer into the media API with no modifier, but either perform the 365*504245a5SDaniel Stoneallocation using implicit modifiers, or allocate the buffer for media use 366*504245a5SDaniel Stoneseparately and copy between the two buffers. 367*504245a5SDaniel Stone 368*504245a5SDaniel StoneAs one exception to the above, allocations may be 'upgraded' from implicit 369*504245a5SDaniel Stoneto explicit modifiers. For example, if the buffer is allocated with 370*504245a5SDaniel Stone``gbm_bo_create`` (taking no modifiers), the user may then query the modifier with 371*504245a5SDaniel Stone``gbm_bo_get_modifier`` and then use this modifier as an explicit modifier token 372*504245a5SDaniel Stoneif a valid modifier is returned. 373*504245a5SDaniel Stone 374*504245a5SDaniel StoneWhen allocating buffers for exchange between different users and modifiers are 375*504245a5SDaniel Stonenot available, implementations are strongly encouraged to use 376*504245a5SDaniel Stone``DRM_FORMAT_MOD_LINEAR`` for their allocation, as this is the universal baseline 377*504245a5SDaniel Stonefor exchange. However, it is not guaranteed that this will result in the correct 378*504245a5SDaniel Stoneinterpretation of buffer content, as implicit modifier operation may still be 379*504245a5SDaniel Stonesubject to driver-specific heuristics. 380*504245a5SDaniel Stone 381*504245a5SDaniel StoneAny new users - userspace programs and protocols, kernel subsystems, etc - 382*504245a5SDaniel Stonewishing to exchange buffers must offer interoperability through dma-buf file 383*504245a5SDaniel Stonedescriptors for memory planes, DRM format tokens to describe the format, DRM 384*504245a5SDaniel Stoneformat modifiers to describe the layout in memory, at least width and height for 385*504245a5SDaniel Stonedimensions, and at least offset and stride for each memory plane. 386*504245a5SDaniel Stone 387*504245a5SDaniel Stone.. _zwp_linux_dmabuf_v1: https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml 388*504245a5SDaniel Stone.. _VK_EXT_image_drm_format_modifier: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_EXT_image_drm_format_modifier.html 389*504245a5SDaniel Stone.. _EGL_EXT_image_dma_buf_import_modifiers: https://registry.khronos.org/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt 390