From a840b3634ad637b237f238d2efb9ab8f4712d5f4 Mon Sep 17 00:00:00 2001 From: Varad Gautam Date: Fri, 10 Feb 2017 13:28:20 +0530 Subject: linux-dmabuf: add immediate dmabuf import path provide a mechanism that allows clients to import the added dmabufs and immediately use the newly created wl_buffers without waiting on an event. this is useful to clients that are sure of their import request succeeding, and wish to avoid the wl_buffer communication roundtrip. bump zwp_linux_dmabuf_v1, zwp_linux_buffer_params_v1 interface versions. v2: specify using incorrectly imported dmabufs as undefined behavior instead of sending success/failure events. (pq, daniels) v3: preserve the optional protocol error added in v2 and explicitly state the outcome of import success or failure (pq) v4: clarify create_immed failure cases and error codes (pq) Signed-off-by: Varad Gautam Reviewed-by: Pekka Paalanen Reviewed-by: Daniel Stone --- unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml | 66 +++++++++++++++++++--- 1 file changed, 59 insertions(+), 7 deletions(-) (limited to 'unstable/linux-dmabuf') diff --git a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml index ed2c4bb..63fbb2d 100644 --- a/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml +++ b/unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml @@ -24,13 +24,13 @@ DEALINGS IN THE SOFTWARE. - + Following the interfaces from: https://www.khronos.org/registry/egl/extensions/EXT/EGL_EXT_image_dma_buf_import.txt and the Linux DRM sub-system's AddFb2 ioctl. - This interface offers a way to create generic dmabuf-based + This interface offers ways to create generic dmabuf-based wl_buffers. Immediately after a client binds to this interface, the set of supported formats is sent with 'format' events. @@ -56,10 +56,23 @@ 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' request is issued. The server - will reply with either a 'created' event which provides the final - wl_buffer or a 'failed' event saying that it cannot use the dmabufs - provided. + 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 @@ -105,7 +118,7 @@ - + This temporary object is a collection of dmabufs and other parameters that together form a single logical buffer. The temporary @@ -138,6 +151,9 @@ summary="invalid width or height"/> + @@ -269,6 +285,42 @@ 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. + + + + + + + + -- cgit v1.2.3