Text of docs.kernel.org › userspace-api › dma-buf-alloc-exchange.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Exchanging pixel buffers — The Linux Kernel documentation

The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs Subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API System calls Security-related interfaces Devices and I/O OpenCAPI (Open Coherent Accelerator Processor Interface) Allocating dma-buf using heaps Exchanging pixel buffers Firmware Control (FWCTL) Userspace API GPIO IOMMUFD Linux Media Infrastructure userspace API Dell Systems Management Base Driver VDUSE - “vDPA Device in Userspace” ISA Plug & Play support Everything else Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source Exchanging pixel buffers ¶ As originally designed, the Linux graphics subsystem had extremely limited support for sharing pixel-buffer allocations between processes, devices, and subsystems.

Modern systems require extensive integration between all three classes; this document details how applications and kernel subsystems should approach this sharing for two-dimensional image data. It is written with reference to the DRM subsystem for GPU and display devices, V4L2 for media devices, and also to Vulkan, EGL and Wayland, for userspace support, however any other subsystems should also follow this design and advice.

Glossary of terms ¶ image: ¶ Conceptually a two-dimensional array of pixels. The pixels may be stored in one or more memory buffers. Has width and height in pixels, pixel format and modifier (implicit or explicit). row: ¶ A span along a single y-axis value, e.g. from co-ordinates (0,100) to (200,100). scanline: ¶ Synonym for row. column: ¶ A span along a single x-axis value, e.g. from co-ordinates (100,0) to (100,100). memory buffer: ¶ A piece of memory for storing (parts of) pixel data.

Has stride and size in bytes and at least one handle in some API. May contain one or more planes. plane: ¶ A two-dimensional array of some or all of an image’s color and alpha channel values. pixel: ¶ A picture element. Has a single color value which is defined by one or more color channels values, e.g. R, G and B, or Y, Cb and Cr. May also have an alpha value as an additional channel. pixel data: ¶ Bytes or bits that represent some or all of the color/alpha channel values of a pixel or an image.

The data for one pixel may be spread over several planes or memory buffers depending on format and modifier. color value: ¶ A tuple of numbers, representing a color. Each element in the tuple is a color channel value. color channel: ¶ One of the dimensions in a color model. For example, RGB model has channels R, G, and B. Alpha channel is sometimes counted as a color channel as well. pixel format: ¶ A description of how pixel data represents the pixel’s color and alpha values. modifier: ¶ A description of how pixel data is laid out in memory buffers. alpha: ¶ A value that denotes the color coverage in a pixel.

Sometimes used for translucency instead. stride: ¶ A value that denotes the relationship between pixel-location co-ordinates and byte-offset values. Typically used as the byte offset between two pixels at the start of vertically-consecutive tiling blocks. For linear layouts, the byte offset between two vertically-adjacent pixels. For non-linear formats the stride must be computed in a consistent way, which usually is done as-if the layout was linear. pitch: ¶ Synonym for stride.

Formats and modifiers ¶ Each buffer must have an underlying format. This format describes the color values provided for each pixel. Although each subsystem has its own format descriptions (e.g. V4L2 and fbdev), the DRM_FORMAT_* tokens should be reused wherever possible, as they are the standard descriptions used for interchange. These tokens are described in the drm_fourcc.h file, which is a part of DRM’s uAPI. Each DRM_FORMAT_* token describes the translation between a pixel co-ordinate in an image, and the color values for that pixel contained within its memory buffers.

The number and type of color channels are described: whether they are RGB or YUV, integer or floating-point, the size of each channel and their locations within the pixel memory, and the relationship between color planes. For example, DRM_FORMAT_ARGB8888 describes a format in which each pixel has a single 32-bit value in memory. Alpha, red, green, and blue, color channels are available at 8-bit precision per channel, ordered respectively from most to least significant bits in little-endian storage.

DRM_FORMAT_* is not affected by either CPU or device endianness; the byte pattern in memory is always as described in the format definition, which is usually little-endian. As a more complex example, DRM_FORMAT_NV12 describes a format in which luma and chroma YUV samples are stored in separate planes, where the chroma plane is stored at half the resolution in both dimensions (i.e. one U/V chroma sample is stored for each 2x2 pixel grouping).

Format modifiers describe a translation mechanism between these per-pixel memory samples, and the actual memory storage for the buffer. The most straightforward modifier is DRM_FORMAT_MOD_LINEAR , describing a scheme in which each plane is laid out row-sequentially, from the top-left to the bottom-right corner. This is considered the baseline interchange format, and most convenient for CPU access. Modern hardware employs much more sophisticated access mechanisms, typically making use of tiled access and possibly also compression.

For example, the DRM_FORMAT_MOD_VIVANTE_TILED modifier describes memory storage where pixels are stored in 4x4 blocks arranged in row-major ordering, i.e. the first tile in a plane stores pixels (0,0) to (3,3) inclusive, and the second tile in a plane stores pixels (4,0) to (7,3) inclusive. Some modifiers may modify the number of planes required for an image; for example, the I915_FORMAT_MOD_Y_TILED_CCS modifier adds a second plane to RGB formats in which it stores data about the status of every tile, notably including whether the tile is fully populated with pixel data, or can be expanded from a single solid color.

These extended layouts are highly vendor-specific, and even specific to particular generations or configurations of devices per-vendor. For this reason, support of modifiers must be explicitly enumerated and negotiated by all users in order to ensure a compatible and optimal pipeline, as discussed below. Dimensions and size ¶ Each pixel buffer must be accompanied by logical pixel dimensions. This refers to the number of unique samples which can be extracted from, or stored to, the underlying memory storage.

For example, even though a 1920x1080 DRM_FORMAT_NV12 buffer has a luma plane containing 1920x1080 samples for the Y component, and 960x540 samples for the U and V components, the overall buffer is still described as having dimensions of 1920x1080. The in-memory storage of a buffer is not guaranteed to begin immediately at the base address of the underlying memory, nor is it guaranteed that the memory storage is tightly clipped to either dimension.

Each plane must therefore be described with an offset in bytes, which will be added to the base address of the memory storage before performing any per-pixel calculations. This may be used to combine multiple planes into a single memory buffer; for example, DRM_FORMAT_NV12 may be stored in a single memory buffer where the luma plane’s storage begins immediately at the start of the buffer with an offset of 0, and the chroma plane’s storage follows within the same buffer beginning from the byte o

The rest of this page is on the live site.