From: Changyeon Lee Date: Wed, 21 Feb 2024 06:43:18 +0000 (+0900) Subject: Revert "linux-dmabuf: update the linux-dmabuf-v1 protocol to a stable version" X-Git-Tag: accepted/tizen/unified/20240304.123058~7 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F15%2F306415%2F2;p=platform%2Fcore%2Fuifw%2Fwayland-extension.git Revert "linux-dmabuf: update the linux-dmabuf-v1 protocol to a stable version" This reverts commit 0b1153fb8250dbdc6971967a7a3fe28f961afd8e. Change-Id: I35e2d73af4a578192a641a4c2f3ef67e8b227c80 --- diff --git a/Makefile.am b/Makefile.am index 3fc4044..1ed2be0 100644 --- a/Makefile.am +++ b/Makefile.am @@ -510,27 +510,11 @@ libsingle_pixel_buffer_v1_client_la_SOURCES = protocol/staging/single-pixel-buff libsingle_pixel_buffer_v1_client_la_CFLAGS = @WAYLAND_CLIENT_CFLAGS@ libsingle_pixel_buffer_v1_client_la_LIBADD = @WAYLAND_CLIENT_LIBS@ -### linux-dmabuf-v1 -protocol_LTLIBRARIES += \ - liblinux-dmabuf-v1-server.la \ - liblinux-dmabuf-v1-client.la -pkgconfig_DATA += \ - src/liblinux-dmabuf-v1-server.pc \ - src/liblinux-dmabuf-v1-client.pc -protocolinclude_HEADERS += \ - protocol/stable/linux-dmabuf-v1-server-protocol.h \ - protocol/stable/linux-dmabuf-v1-client-protocol.h -liblinux_dmabuf_v1_server_la_SOURCES = protocol/stable/linux-dmabuf-v1-protocol.c -liblinux_dmabuf_v1_server_la_CFLAGS = @WAYLAND_SERVER_CFLAGS@ -liblinux_dmabuf_v1_server_la_LIBADD = @WAYLAND_SERVER_LIBS@ -liblinux_dmabuf_v1_client_la_SOURCES = protocol/stable/linux-dmabuf-v1-protocol.c -liblinux_dmabuf_v1_client_la_CFLAGS = @WAYLAND_CLIENT_CFLAGS@ -liblinux_dmabuf_v1_client_la_LIBADD = @WAYLAND_CLIENT_LIBS@ - ### wayland-protocols unstable_protocols = \ protocol/unstable/pointer-gestures/pointer-gestures-unstable-v1.xml \ protocol/unstable/fullscreen-shell/fullscreen-shell-unstable-v1.xml \ + protocol/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml \ protocol/unstable/text-input/text-input-unstable-v1.xml \ protocol/unstable/text-input/text-input-unstable-v3.xml \ protocol/unstable/input-method/input-method-unstable-v1.xml \ @@ -560,7 +544,6 @@ stable_protocols = \ protocol/stable/presentation-time/presentation-time.xml \ protocol/stable/viewporter/viewporter.xml \ protocol/stable/xdg-shell/xdg-shell.xml \ - protocol/stable/linux-dmabuf/linux-dmabuf-v1.xml \ $(NULL) tizen_protocols = \ diff --git a/protocol/stable/linux-dmabuf/README b/protocol/stable/linux-dmabuf/README deleted file mode 100644 index cdedf98..0000000 --- a/protocol/stable/linux-dmabuf/README +++ /dev/null @@ -1,5 +0,0 @@ -Linux DMA-BUF protocol - -Maintainers: -Pekka Paalanen -Daniel Stone diff --git a/protocol/stable/linux-dmabuf/feedback.rst b/protocol/stable/linux-dmabuf/feedback.rst deleted file mode 100644 index a3f94ed..0000000 --- a/protocol/stable/linux-dmabuf/feedback.rst +++ /dev/null @@ -1,218 +0,0 @@ -.. Copyright 2021 Simon Ser - -.. contents:: - - -linux-dmabuf feedback introduction -================================== - -linux-dmabuf feedback allows compositors and clients to negotiate optimal buffer -allocation parameters. This document will assume that the compositor is using a -rendering API such as OpenGL or Vulkan and KMS as the presentation API: even if -linux-dmabuf feedback isn't restricted to this use-case, it's the most common. - -linux-dmabuf feedback introduces the following concepts: - -1. A main device. This is the render device that the compositor is using to - perform composition. Compositors should always be able to display a buffer - submitted by a client, so this device can be used as a fallback in case none - of the more optimized code-paths work. Clients should allocate buffers such - that they can be imported and textured from the main device. - -2. One or more tranches. Each tranche consists of a target device, allocation - flags and a set of format/modifier pairs. A tranche can be seen as a set of - formats/modifier pairs that are compatible with the target device. - - A tranche can have the ``scanout`` flag. It means that the target device is - a KMS device, and that buffers allocated with one of the format/modifier - pairs in the tranche are eligible for direct scanout. - - Clients should use the tranches in order to allocate buffers with the most - appropriate format/modifier and also to avoid allocating in private device - memory when cross-device operations are going to happen. - -linux-dmabuf feedback implementation notes -========================================== - -This section contains recommendations for client and compositor implementations. - -For clients ------------ - -Clients are expected to either pick a fixed DRM format beforehand, or -perform the following steps repeatedly until they find a suitable format. - -Basic clients may only support static buffer allocation on startup. These -clients should do the following: - -1. Send a ``get_default_feedback`` request to get global feedback. -2. Select the device indicated by ``main_device`` for allocation. -3. For each tranche: - - 1. If ``tranche_target_device`` doesn't match the allocation device, ignore - the tranche. - 2. Accumulate allocation flags from ``tranche_flags``. - 3. Accumulate format/modifier pairs received via ``tranche_formats`` in a - list. - 4. When the ``tranche_done`` event is received, try to allocate the buffer - with the accumulated list of modifiers and allocation flags. If that - fails, proceed with the next tranche. If that succeeds, stop the loop. - -4. Destroy the feedback object. - -Tranches are ordered by preference: the more optimized tranches come first. As -such, clients should use the first tranche that happens to work. - -Some clients may have already selected the device they want to use beforehand. -These clients can ignore the ``main_device`` event, and ignore tranches whose -``tranche_target_device`` doesn't match the selected device. Such clients need -to be prepared for the ``wp_linux_buffer_params.create`` request to potentially -fail. - -If the client allocates a buffer without specifying explicit modifiers on a -device different from the one indicated by ``main_device``, then the client -must force a linear layout. - -Some clients might support re-negotiating the buffer format/modifier on the -fly. These clients should send a ``get_surface_feedback`` request and keep the -feedback object alive after the initial allocation. Each time a new set of -feedback parameters is received (ended by the ``done`` event), they should -perform the same steps as basic clients described above. They should detect -when the optimal allocation parameters didn't change (same -format/modifier/flags) to avoid needlessly re-allocating their buffers. - -Some clients might additionally support switching the device used for -allocations on the fly. Such clients should send a ``get_surface_feedback`` -request. For each tranche, select the device indicated by -``tranche_target_device`` for allocation. Accumulate allocation flags (received -via ``tranche_flags``) and format/modifier pairs (received via -``tranche_formats``) as usual. When the ``tranche_done`` event is received, try -to allocate the buffer with the accumulated list of modifiers and the -allocation flags. Try to import the resulting buffer by sending a -``wp_linux_buffer_params.create`` request (this might fail). Repeat with each -tranche until an allocation and import succeeds. Each time a new set of -feedback parameters is received, they should perform these steps again. They -should detect when the optimal allocation parameters didn't change (same -device/format/modifier/flags) to avoid needlessly re-allocating their buffers. - -For compositors ---------------- - -Basic compositors may only support texturing the DMA-BUFs via a rendering API -such as OpenGL or Vulkan. Such compositors can send a single tranche as a reply -to both ``get_default_feedback`` and ``get_surface_feedback``. Set the -``main_device`` to the rendering device. Send the tranche with -``tranche_target_device`` set to the rendering device and all of the DRM -format/modifier pairs supported by the rendering API. Do not set the -``scanout`` flag in the ``tranche_flags`` event. - -Some compositors may support direct scan-out for full-screen surfaces. These -compositors can re-send the feedback parameters when a surface becomes -full-screen or leaves full-screen mode if the client has used the -``get_surface_feedback`` request. The non-full-screen feedback parameters are -the same as basic compositors described above. The full-screen feedback -parameters have two tranches: one with the format/modifier pairs supported by -the KMS plane, with the ``scanout`` flag set in the ``tranche_flags`` event and -with ``tranche_target_device`` set to the KMS scan-out device; the other with -the rest of the format/modifier pairs (supported for texturing, but not for -scan-out), without the ``scanout`` flag set in the ``tranche_flags`` event, and -with the ``tranche_target_device`` set to the rendering device. - -Some compositors may support direct scan-out for all surfaces. These -compositors can send two tranches for surfaces that become candidates for -direct scan-out, similarly to compositors supporting direct scan-out for -fullscreen surfaces. When a surface stops being a candidate for direct -scan-out, compositors should re-send the feedback parameters optimized for -texturing only. The way candidates for direct scan-out are selected is -compositor policy, a possible implementation is to select as many surfaces as -there are available hardware planes, starting from surfaces closer to the eye. - -Some compositors may support multiple devices at the same time. If the -compositor supports rendering with a fixed device and direct scan-out on a -secondary device, it may send a separate tranche for surfaces displayed on -the secondary device that are candidates for direct scan-out. The -``tranche_target_device`` for this tranche will be the secondary device and -will not match the ``main_device``. - -Some compositors may support switching their rendering device at runtime or -changing their rendering device depending on the surface. When the rendering -device changes for a surface, such compositors may re-send the feedback -parameters with a different ``main_device``. However there is a risk that -clients don't support switching their device at runtime and continue using the -previous device. For this reason, compositors should always have a fallback -rendering device that they initially send as ``main_device``, such that these -clients use said fallback device. - -Compositors should not change the ``main_device`` on-the-fly when explicit -modifiers are not supported, because there's a risk of importing buffers -with an implicit non-linear modifier as a linear buffer, resulting in -misinterpreted buffer contents. - -Compositors should not send feedback parameters if they don't have a fallback -path. For instance, compositors shouldn't send a format/modifier supported for -direct scan-out but not supported by the rendering API for texturing. - -Compositors can decide to use multiple tranches to describe the allocation -parameters optimized for texturing. For example, if there are formats which -have a fast texturing path and formats which have a slower texturing path, the -compositor can decide to expose two separate tranches. - -Compositors can decide to use intermediate tranches to describe code-paths -slower than direct scan-out but faster than texturing. For instance, a -compositor could insert an intermediate tranche if it's possible to use a -mem2mem device to convert buffers to be able to use scan-out. - -``dev_t`` encoding -================== - -The protocol carries ``dev_t`` values on the wire using arrays. A compositor -written in C can encode the values as follows: - -.. code-block:: c - - struct stat drm_node_stat; - struct wl_array dev_array = { - .size = sizeof(drm_node_stat.st_rdev), - .data = &drm_node_stat.st_rdev, - }; - -A client can decode the values as follows: - -.. code-block:: c - - dev_t dev; - assert(dev_array->size == sizeof(dev)); - memcpy(&dev, dev_array->data, sizeof(dev)); - -Because two DRM nodes can refer to the same DRM device while having different -``dev_t`` values, clients should use ``drmDevicesEqual`` to compare two -devices. - -``format_table`` encoding -========================= - -The ``format_table`` event carries a file descriptor containing a list of -format + modifier pairs. The list is an array of pairs which can be accessed -with this C structure definition: - -.. code-block:: c - - struct dmabuf_format_modifier { - uint32_t format; - uint32_t pad; /* unused */ - uint64_t modifier; - }; - -Integration with other APIs -=========================== - -- libdrm: ``drmGetDeviceFromDevId`` returns a ``drmDevice`` from a device ID. -- EGL: the `EGL_EXT_device_drm_render_node`_ extension may be used to query the - DRM device render node used by a given EGL display. When unavailable, the - older `EGL_EXT_device_drm`_ extension may be used as a fallback. -- Vulkan: the `VK_EXT_physical_device_drm`_ extension may be used to query the - DRM device used by a given ``VkPhysicalDevice``. - -.. _EGL_EXT_device_drm: https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_drm.txt -.. _EGL_EXT_device_drm_render_node: https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_device_drm_render_node.txt -.. _VK_EXT_physical_device_drm: https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/VK_EXT_physical_device_drm.html diff --git a/protocol/stable/linux-dmabuf/linux-dmabuf-v1.xml b/protocol/stable/linux-dmabuf/linux-dmabuf-v1.xml deleted file mode 100644 index 38e06f5..0000000 --- a/protocol/stable/linux-dmabuf/linux-dmabuf-v1.xml +++ /dev/null @@ -1,585 +0,0 @@ - - - - - Copyright © 2014, 2015 Collabora, Ltd. - - Permission is hereby granted, free of charge, to any person obtaining a - copy of this software and associated documentation files (the "Software"), - to deal in the Software without restriction, including without limitation - the rights to use, copy, modify, merge, publish, distribute, sublicense, - and/or sell copies of the Software, and to permit persons to whom the - Software is furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice (including the next - paragraph) shall be included in all copies or substantial portions of the - Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL - THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. - - - - - Following the interfaces from: - https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt - https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt - and the Linux DRM sub-system's AddFb2 ioctl. - - This interface offers ways to create generic dmabuf-based wl_buffers. - - Clients can use the get_surface_feedback request to get dmabuf feedback - for a particular surface. If the client wants to retrieve feedback not - tied to a surface, they can use the get_default_feedback request. - - The following are required from clients: - - - Clients must ensure that either all data in the dma-buf is - coherent for all subsequent read access or that coherency is - correctly handled by the underlying kernel-side dma-buf - implementation. - - - Don't make any more attachments after sending the buffer to the - compositor. Making more attachments later increases the risk of - the compositor not being able to use (re-import) an existing - dmabuf-based wl_buffer. - - The underlying graphics stack must ensure the following: - - - The dmabuf file descriptors relayed to the server will stay valid - for the whole lifetime of the wl_buffer. This means the server may - at any time use those fds to import the dmabuf into any kernel - sub-system that might accept it. - - However, when the underlying graphics stack fails to deliver the - promise, because of e.g. a device hot-unplug which raises internal - errors, after the wl_buffer has been successfully created the - compositor must not raise protocol errors to the client when dmabuf - import later fails. - - To create a wl_buffer from one or more dmabufs, a client creates a - zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params - request. All planes required by the intended format are added with - the 'add' request. Finally, a 'create' or 'create_immed' request is - issued, which has the following outcome depending on the import success. - - The 'create' request, - - on success, triggers a 'created' event which provides the final - wl_buffer to the client. - - on failure, triggers a 'failed' event to convey that the server - cannot use the dmabufs received from the client. - - For the 'create_immed' request, - - on success, the server immediately imports the added dmabufs to - create a wl_buffer. No event is sent from the server in this case. - - on failure, the server can choose to either: - - terminate the client by raising a fatal error. - - mark the wl_buffer as failed, and send a 'failed' event to the - client. If the client uses a failed wl_buffer as an argument to any - request, the behaviour is compositor implementation-defined. - - For all DRM formats and unless specified in another protocol extension, - pre-multiplied alpha is used for pixel values. - - Unless specified otherwise in another protocol extension, implicit - synchronization is used. In other words, compositors and clients must - wait and signal fences implicitly passed via the DMA-BUF's reservation - mechanism. - - - - - Objects created through this interface, especially wl_buffers, will - remain valid. - - - - - - This temporary object is used to collect multiple dmabuf handles into - a single batch to create a wl_buffer. It can only be used once and - should be destroyed after a 'created' or 'failed' event has been - received. - - - - - - - This event advertises one buffer format that the server supports. - All the supported formats are advertised once when the client - binds to this interface. A roundtrip after binding guarantees - that the client has received all supported formats. - - For the definition of the format codes, see the - zwp_linux_buffer_params_v1::create request. - - Starting version 4, the format event is deprecated and must not be - sent by compositors. Instead, use get_default_feedback or - get_surface_feedback. - - - - - - - This event advertises the formats that the server supports, along with - the modifiers supported for each format. All the supported modifiers - for all the supported formats are advertised once when the client - binds to this interface. A roundtrip after binding guarantees that - the client has received all supported format-modifier pairs. - - For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi == - 0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event. - It indicates that the server can support the format with an implicit - modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it - is as if no explicit modifier is specified. The effective modifier - will be derived from the dmabuf. - - A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for - a given format supports both explicit modifiers and implicit modifiers. - - For the definition of the format and modifier codes, see the - zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add - requests. - - Starting version 4, the modifier event is deprecated and must not be - sent by compositors. Instead, use get_default_feedback or - get_surface_feedback. - - - - - - - - - - - This request creates a new wp_linux_dmabuf_feedback object not bound - to a particular surface. This object will deliver feedback about dmabuf - parameters to use if the client doesn't support per-surface feedback - (see get_surface_feedback). - - - - - - - This request creates a new wp_linux_dmabuf_feedback object for the - specified wl_surface. This object will deliver feedback about dmabuf - parameters to use for buffers attached to this surface. - - If the surface is destroyed before the wp_linux_dmabuf_feedback object, - the feedback object becomes inert. - - - - - - - - - This temporary object is a collection of dmabufs and other - parameters that together form a single logical buffer. The temporary - object may eventually create one wl_buffer unless cancelled by - destroying it before requesting 'create'. - - Single-planar formats only require one dmabuf, however - multi-planar formats may require more than one dmabuf. For all - formats, an 'add' request must be called once per plane (even if the - underlying dmabuf fd is identical). - - You must use consecutive plane indices ('plane_idx' argument for 'add') - from zero to the number of planes used by the drm_fourcc format code. - All planes required by the format must be given exactly once, but can - be given in any order. Each plane index can be set only once. - - - - - - - - - - - - - - - - Cleans up the temporary data sent to the server for dmabuf-based - wl_buffer creation. - - - - - - This request adds one dmabuf to the set in this - zwp_linux_buffer_params_v1. - - The 64-bit unsigned value combined from modifier_hi and modifier_lo - is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the - fb modifier, which is defined in drm_mode.h of Linux UAPI. - This is an opaque token. Drivers use this token to express tiling, - compression, etc. driver-specific modifications to the base format - defined by the DRM fourcc code. - - Starting from version 4, the invalid_format protocol error is sent if - the format + modifier pair was not advertised as supported. - - Starting from version 5, the invalid_format protocol error is sent if - all planes don't use the same modifier. - - This request raises the PLANE_IDX error if plane_idx is too large. - The error PLANE_SET is raised if attempting to set a plane that - was already set. - - - - - - - - - - - - - - - - - - This asks for creation of a wl_buffer from the added dmabuf - buffers. The wl_buffer is not created immediately but returned via - the 'created' event if the dmabuf sharing succeeds. The sharing - may fail at runtime for reasons a client cannot predict, in - which case the 'failed' event is triggered. - - The 'format' argument is a DRM_FORMAT code, as defined by the - libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the - authoritative source on how the format codes should work. - - The 'flags' is a bitfield of the flags defined in enum "flags". - 'y_invert' means the that the image needs to be y-flipped. - - Flag 'interlaced' means that the frame in the buffer is not - progressive as usual, but interlaced. An interlaced buffer as - supported here must always contain both top and bottom fields. - The top field always begins on the first pixel row. The temporal - ordering between the two fields is top field first, unless - 'bottom_first' is specified. It is undefined whether 'bottom_first' - is ignored if 'interlaced' is not set. - - This protocol does not convey any information about field rate, - duration, or timing, other than the relative ordering between the - two fields in one buffer. A compositor may have to estimate the - intended field rate from the incoming buffer rate. It is undefined - whether the time of receiving wl_surface.commit with a new buffer - attached, applying the wl_surface state, wl_surface.frame callback - trigger, presentation, or any other point in the compositor cycle - is used to measure the frame or field times. There is no support - for detecting missed or late frames/fields/buffers either, and - there is no support whatsoever for cooperating with interlaced - compositor output. - - The composited image quality resulting from the use of interlaced - buffers is explicitly undefined. A compositor may use elaborate - hardware features or software to deinterlace and create progressive - output frames from a sequence of interlaced input buffers, or it - may produce substandard image quality. However, compositors that - cannot guarantee reasonable image quality in all cases are recommended - to just reject all interlaced buffers. - - Any argument errors, including non-positive width or height, - mismatch between the number of planes and the format, bad - format, bad offset or stride, may be indicated by fatal protocol - errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, - OUT_OF_BOUNDS. - - Dmabuf import errors in the server that are not obvious client - bugs are returned via the 'failed' event as non-fatal. This - allows attempting dmabuf sharing and falling back in the client - if it fails. - - This request can be sent only once in the object's lifetime, after - which the only legal request is destroy. This object should be - destroyed after issuing a 'create' request. Attempting to use this - object after issuing 'create' raises ALREADY_USED protocol error. - - It is not mandatory to issue 'create'. If a client wants to - cancel the buffer creation, it can just destroy this object. - - - - - - - - - - This event indicates that the attempted buffer creation was - successful. It provides the new wl_buffer referencing the dmabuf(s). - - Upon receiving this event, the client should destroy the - zwp_linux_buffer_params_v1 object. - - - - - - - This event indicates that the attempted buffer creation has - failed. It usually means that one of the dmabuf constraints - has not been fulfilled. - - Upon receiving this event, the client should destroy the - zwp_linux_buffer_params_v1 object. - - - - - - This asks for immediate creation of a wl_buffer by importing the - added dmabufs. - - In case of import success, no event is sent from the server, and the - wl_buffer is ready to be used by the client. - - Upon import failure, either of the following may happen, as seen fit - by the implementation: - - the client is terminated with one of the following fatal protocol - errors: - - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS, - in case of argument errors such as mismatch between the number - of planes and the format, bad format, non-positive width or - height, or bad offset or stride. - - INVALID_WL_BUFFER, in case the cause for failure is unknown or - plaform specific. - - the server creates an invalid wl_buffer, marks it as failed and - sends a 'failed' event to the client. The result of using this - invalid wl_buffer as an argument in any request by the client is - defined by the compositor implementation. - - This takes the same arguments as a 'create' request, and obeys the - same restrictions. - - - - - - - - - - - - This object advertises dmabuf parameters feedback. This includes the - preferred devices and the supported formats/modifiers. - - The parameters are sent once when this object is created and whenever they - change. The done event is always sent once after all parameters have been - sent. When a single parameter changes, all parameters are re-sent by the - compositor. - - Compositors can re-send the parameters when the current client buffer - allocations are sub-optimal. Compositors should not re-send the - parameters if re-allocating the buffers would not result in a more optimal - configuration. In particular, compositors should avoid sending the exact - same parameters multiple times in a row. - - The tranche_target_device and tranche_formats events are grouped by - tranches of preference. For each tranche, a tranche_target_device, one - tranche_flags and one or more tranche_formats events are sent, followed - by a tranche_done event finishing the list. The tranches are sent in - descending order of preference. All formats and modifiers in the same - tranche have the same preference. - - To send parameters, the compositor sends one main_device event, tranches - (each consisting of one tranche_target_device event, one tranche_flags - event, tranche_formats events and then a tranche_done event), then one - done event. - - - - - Using this request a client can tell the server that it is not going to - use the wp_linux_dmabuf_feedback object anymore. - - - - - - This event is sent after all parameters of a wp_linux_dmabuf_feedback - object have been sent. - - This allows changes to the wp_linux_dmabuf_feedback parameters to be - seen as atomic, even if they happen via multiple events. - - - - - - This event provides a file descriptor which can be memory-mapped to - access the format and modifier table. - - The table contains a tightly packed array of consecutive format + - modifier pairs. Each pair is 16 bytes wide. It contains a format as a - 32-bit unsigned integer, followed by 4 bytes of unused padding, and a - modifier as a 64-bit unsigned integer. The native endianness is used. - - The client must map the file descriptor in read-only private mode. - - Compositors are not allowed to mutate the table file contents once this - event has been sent. Instead, compositors must create a new, separate - table file and re-send feedback parameters. Compositors are allowed to - store duplicate format + modifier pairs in the table. - - - - - - - - This event advertises the main device that the server prefers to use - when direct scan-out to the target device isn't possible. The - advertised main device may be different for each - wp_linux_dmabuf_feedback object, and may change over time. - - There is exactly one main device. The compositor must send at least - one preference tranche with tranche_target_device equal to main_device. - - Clients need to create buffers that the main device can import and - read from, otherwise creating the dmabuf wl_buffer will fail (see the - wp_linux_buffer_params.create and create_immed requests for details). - The main device will also likely be kept active by the compositor, - so clients can use it instead of waking up another device for power - savings. - - In general the device is a DRM node. The DRM node type (primary vs. - render) is unspecified. Clients must not rely on the compositor sending - a particular node type. Clients cannot check two devices for equality - by comparing the dev_t value. - - If explicit modifiers are not supported and the client performs buffer - allocations on a different device than the main device, then the client - must force the buffer to have a linear layout. - - - - - - - This event splits tranche_target_device and tranche_formats events in - preference tranches. It is sent after a set of tranche_target_device - and tranche_formats events; it represents the end of a tranche. The - next tranche will have a lower preference. - - - - - - This event advertises the target device that the server prefers to use - for a buffer created given this tranche. The advertised target device - may be different for each preference tranche, and may change over time. - - There is exactly one target device per tranche. - - The target device may be a scan-out device, for example if the - compositor prefers to directly scan-out a buffer created given this - tranche. The target device may be a rendering device, for example if - the compositor prefers to texture from said buffer. - - The client can use this hint to allocate the buffer in a way that makes - it accessible from the target device, ideally directly. The buffer must - still be accessible from the main device, either through direct import - or through a potentially more expensive fallback path. If the buffer - can't be directly imported from the main device then clients must be - prepared for the compositor changing the tranche priority or making - wl_buffer creation fail (see the wp_linux_buffer_params.create and - create_immed requests for details). - - If the device is a DRM node, the DRM node type (primary vs. render) is - unspecified. Clients must not rely on the compositor sending a - particular node type. Clients cannot check two devices for equality by - comparing the dev_t value. - - This event is tied to a preference tranche, see the tranche_done event. - - - - - - - This event advertises the format + modifier combinations that the - compositor supports. - - It carries an array of indices, each referring to a format + modifier - pair in the last received format table (see the format_table event). - Each index is a 16-bit unsigned integer in native endianness. - - For legacy support, DRM_FORMAT_MOD_INVALID is an allowed modifier. - It indicates that the server can support the format with an implicit - modifier. When a buffer has DRM_FORMAT_MOD_INVALID as its modifier, it - is as if no explicit modifier is specified. The effective modifier - will be derived from the dmabuf. - - A compositor that sends valid modifiers and DRM_FORMAT_MOD_INVALID for - a given format supports both explicit modifiers and implicit modifiers. - - Compositors must not send duplicate format + modifier pairs within the - same tranche or across two different tranches with the same target - device and flags. - - This event is tied to a preference tranche, see the tranche_done event. - - For the definition of the format and modifier codes, see the - wp_linux_buffer_params.create request. - - - - - - - - - - - This event sets tranche-specific flags. - - The scanout flag is a hint that direct scan-out may be attempted by the - compositor on the target device if the client appropriately allocates a - buffer. How to allocate a buffer that can be scanned out on the target - device is implementation-defined. - - This event is tied to a preference tranche, see the tranche_done event. - - - - - - diff --git a/protocol/unstable/linux-dmabuf/README b/protocol/unstable/linux-dmabuf/README new file mode 100644 index 0000000..cdedf98 --- /dev/null +++ b/protocol/unstable/linux-dmabuf/README @@ -0,0 +1,5 @@ +Linux DMA-BUF protocol + +Maintainers: +Pekka Paalanen +Daniel Stone diff --git a/protocol/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml b/protocol/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml new file mode 100644 index 0000000..b43e81c --- /dev/null +++ b/protocol/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml @@ -0,0 +1,362 @@ + + + + + Copyright © 2014, 2015 Collabora, Ltd. + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice (including the next + paragraph) shall be included in all copies or substantial portions of the + Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. + + + + + Following the interfaces from: + https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt + https://www.khronos.org/registry/EGL/extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt + and the Linux DRM sub-system's AddFb2 ioctl. + + This interface offers ways to create generic dmabuf-based + wl_buffers. Immediately after a client binds to this interface, + the set of supported formats and format modifiers is sent with + 'format' and 'modifier' events. + + The following are required from clients: + + - Clients must ensure that either all data in the dma-buf is + coherent for all subsequent read access or that coherency is + correctly handled by the underlying kernel-side dma-buf + implementation. + + - Don't make any more attachments after sending the buffer to the + compositor. Making more attachments later increases the risk of + the compositor not being able to use (re-import) an existing + dmabuf-based wl_buffer. + + The underlying graphics stack must ensure the following: + + - The dmabuf file descriptors relayed to the server will stay valid + for the whole lifetime of the wl_buffer. This means the server may + at any time use those fds to import the dmabuf into any kernel + sub-system that might accept it. + + To create a wl_buffer from one or more dmabufs, a client creates a + zwp_linux_dmabuf_params_v1 object with a zwp_linux_dmabuf_v1.create_params + request. All planes required by the intended format are added with + the 'add' request. Finally, a 'create' or 'create_immed' request is + issued, which has the following outcome depending on the import success. + + The 'create' request, + - on success, triggers a 'created' event which provides the final + wl_buffer to the client. + - on failure, triggers a 'failed' event to convey that the server + cannot use the dmabufs received from the client. + + For the 'create_immed' request, + - on success, the server immediately imports the added dmabufs to + create a wl_buffer. No event is sent from the server in this case. + - on failure, the server can choose to either: + - terminate the client by raising a fatal error. + - mark the wl_buffer as failed, and send a 'failed' event to the + client. If the client uses a failed wl_buffer as an argument to any + request, the behaviour is compositor implementation-defined. + + Warning! The protocol described in this file is experimental and + backward incompatible changes may be made. Backward compatible changes + may be added together with the corresponding interface version bump. + Backward incompatible changes are done by bumping the version number in + the protocol and interface names and resetting the interface version. + Once the protocol is to be declared stable, the 'z' prefix and the + version number in the protocol and interface names are removed and the + interface version number is reset. + + + + + Objects created through this interface, especially wl_buffers, will + remain valid. + + + + + + This temporary object is used to collect multiple dmabuf handles into + a single batch to create a wl_buffer. It can only be used once and + should be destroyed after a 'created' or 'failed' event has been + received. + + + + + + + This event advertises one buffer format that the server supports. + All the supported formats are advertised once when the client + binds to this interface. A roundtrip after binding guarantees + that the client has received all supported formats. + + For the definition of the format codes, see the + zwp_linux_buffer_params_v1::create request. + + Warning: the 'format' event is likely to be deprecated and replaced + with the 'modifier' event introduced in zwp_linux_dmabuf_v1 + version 3, described below. Please refrain from using the information + received from this event. + + + + + + + This event advertises the formats that the server supports, along with + the modifiers supported for each format. All the supported modifiers + for all the supported formats are advertised once when the client + binds to this interface. A roundtrip after binding guarantees that + the client has received all supported format-modifier pairs. + + For legacy support, DRM_FORMAT_MOD_INVALID (that is, modifier_hi == + 0x00ffffff and modifier_lo == 0xffffffff) is allowed in this event. + It indicates that the server can support the format with an implicit + modifier. When a plane has DRM_FORMAT_MOD_INVALID as its modifier, it + is as if no explicit modifier is specified. The effective modifier + will be derived from the dmabuf. + + For the definition of the format and modifier codes, see the + zwp_linux_buffer_params_v1::create and zwp_linux_buffer_params_v1::add + requests. + + + + + + + + + + This temporary object is a collection of dmabufs and other + parameters that together form a single logical buffer. The temporary + object may eventually create one wl_buffer unless cancelled by + destroying it before requesting 'create'. + + Single-planar formats only require one dmabuf, however + multi-planar formats may require more than one dmabuf. For all + formats, an 'add' request must be called once per plane (even if the + underlying dmabuf fd is identical). + + You must use consecutive plane indices ('plane_idx' argument for 'add') + from zero to the number of planes used by the drm_fourcc format code. + All planes required by the format must be given exactly once, but can + be given in any order. Each plane index can be set only once. + + + + + + + + + + + + + + + + Cleans up the temporary data sent to the server for dmabuf-based + wl_buffer creation. + + + + + + This request adds one dmabuf to the set in this + zwp_linux_buffer_params_v1. + + The 64-bit unsigned value combined from modifier_hi and modifier_lo + is the dmabuf layout modifier. DRM AddFB2 ioctl calls this the + fb modifier, which is defined in drm_mode.h of Linux UAPI. + This is an opaque token. Drivers use this token to express tiling, + compression, etc. driver-specific modifications to the base format + defined by the DRM fourcc code. + + Warning: It should be an error if the format/modifier pair was not + advertised with the modifier event. This is not enforced yet because + some implementations always accept DRM_FORMAT_MOD_INVALID. Also + version 2 of this protocol does not have the modifier event. + + This request raises the PLANE_IDX error if plane_idx is too large. + The error PLANE_SET is raised if attempting to set a plane that + was already set. + + + + + + + + + + + + + + + + + + This asks for creation of a wl_buffer from the added dmabuf + buffers. The wl_buffer is not created immediately but returned via + the 'created' event if the dmabuf sharing succeeds. The sharing + may fail at runtime for reasons a client cannot predict, in + which case the 'failed' event is triggered. + + The 'format' argument is a DRM_FORMAT code, as defined by the + libdrm's drm_fourcc.h. The Linux kernel's DRM sub-system is the + authoritative source on how the format codes should work. + + The 'flags' is a bitfield of the flags defined in enum "flags". + 'y_invert' means the that the image needs to be y-flipped. + + Flag 'interlaced' means that the frame in the buffer is not + progressive as usual, but interlaced. An interlaced buffer as + supported here must always contain both top and bottom fields. + The top field always begins on the first pixel row. The temporal + ordering between the two fields is top field first, unless + 'bottom_first' is specified. It is undefined whether 'bottom_first' + is ignored if 'interlaced' is not set. + + This protocol does not convey any information about field rate, + duration, or timing, other than the relative ordering between the + two fields in one buffer. A compositor may have to estimate the + intended field rate from the incoming buffer rate. It is undefined + whether the time of receiving wl_surface.commit with a new buffer + attached, applying the wl_surface state, wl_surface.frame callback + trigger, presentation, or any other point in the compositor cycle + is used to measure the frame or field times. There is no support + for detecting missed or late frames/fields/buffers either, and + there is no support whatsoever for cooperating with interlaced + compositor output. + + The composited image quality resulting from the use of interlaced + buffers is explicitly undefined. A compositor may use elaborate + hardware features or software to deinterlace and create progressive + output frames from a sequence of interlaced input buffers, or it + may produce substandard image quality. However, compositors that + cannot guarantee reasonable image quality in all cases are recommended + to just reject all interlaced buffers. + + Any argument errors, including non-positive width or height, + mismatch between the number of planes and the format, bad + format, bad offset or stride, may be indicated by fatal protocol + errors: INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, + OUT_OF_BOUNDS. + + Dmabuf import errors in the server that are not obvious client + bugs are returned via the 'failed' event as non-fatal. This + allows attempting dmabuf sharing and falling back in the client + if it fails. + + This request can be sent only once in the object's lifetime, after + which the only legal request is destroy. This object should be + destroyed after issuing a 'create' request. Attempting to use this + object after issuing 'create' raises ALREADY_USED protocol error. + + It is not mandatory to issue 'create'. If a client wants to + cancel the buffer creation, it can just destroy this object. + + + + + + + + + + This event indicates that the attempted buffer creation was + successful. It provides the new wl_buffer referencing the dmabuf(s). + + Upon receiving this event, the client should destroy the + zlinux_dmabuf_params object. + + + + + + + This event indicates that the attempted buffer creation has + failed. It usually means that one of the dmabuf constraints + has not been fulfilled. + + Upon receiving this event, the client should destroy the + zlinux_buffer_params object. + + + + + + This asks for immediate creation of a wl_buffer by importing the + added dmabufs. + + In case of import success, no event is sent from the server, and the + wl_buffer is ready to be used by the client. + + Upon import failure, either of the following may happen, as seen fit + by the implementation: + - the client is terminated with one of the following fatal protocol + errors: + - INCOMPLETE, INVALID_FORMAT, INVALID_DIMENSIONS, OUT_OF_BOUNDS, + in case of argument errors such as mismatch between the number + of planes and the format, bad format, non-positive width or + height, or bad offset or stride. + - INVALID_WL_BUFFER, in case the cause for failure is unknown or + plaform specific. + - the server creates an invalid wl_buffer, marks it as failed and + sends a 'failed' event to the client. The result of using this + invalid wl_buffer as an argument in any request by the client is + defined by the compositor implementation. + + This takes the same arguments as a 'create' request, and obeys the + same restrictions. + + + + + + + + + + +