From 86b4724eb35ce0b8671014e96307cd7c35a3c6fd Mon Sep 17 00:00:00 2001 From: Xaver Hugl Date: Sun, 10 Dec 2023 20:49:45 +0100 Subject: [PATCH] stable/linux-dmabuf: allow compositors to advertise multiple devices With multi gpu systems, if the client is rendering on a device other than the main_device advertised by the compositor, there's no way for the client to know whether or not the import will be successful except for allocating a buffer and attempting to import the buffer into the target device, and if that fails, trying again with different formats, modifiers and potentially allocation flags. Similarly, compositors that want to supoprt buffers from non-main devices need to attempt importing the buffer to every device they support. In some cases, this import may even trigger expensive operations such as the buffer being copied into system memory by the kernel. This protocol addition allows compositors to explicitly advertise support for multiple devices on the system, and specify which formats and modifiers they can sample from. For buffer imports, the client explicitly specifies a device for the compositor to import the buffer to, which allows the compositor to avoid additional copies. Signed-off-by: Xaver Hugl --- stable/linux-dmabuf/linux-dmabuf-v1.xml | 73 ++++++++++++++++++------- 1 file changed, 53 insertions(+), 20 deletions(-) diff --git a/stable/linux-dmabuf/linux-dmabuf-v1.xml b/stable/linux-dmabuf/linux-dmabuf-v1.xml index 12d09fb..647000f 100644 --- a/stable/linux-dmabuf/linux-dmabuf-v1.xml +++ b/stable/linux-dmabuf/linux-dmabuf-v1.xml @@ -24,7 +24,7 @@ DEALINGS IN THE SOFTWARE. - + This interface offers ways to create generic dmabuf-based wl_buffers. @@ -184,7 +184,7 @@ - + This temporary object is a collection of dmabufs and other parameters that together form a single logical buffer. The temporary @@ -394,9 +394,25 @@ + + + + Set the device the compositor should import the dmabufs to for sampling + in the next create or create_immed request. + + To avoid race conditions when the compositor removes a device from the + tranches, it is not a protocol error if the device hasn't been advertised + by the compositor in a tranche with the sampling flag, but the import is + likely to fail in that case. + + If the client doesn't know a suitable target device, it shouldn't set one, + and the compositor should attempt import on all devices it supports. + + + - + This object advertises dmabuf parameters feedback. This includes the preferred devices and the supported formats/modifiers. @@ -419,10 +435,13 @@ 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. + To send parameters, the compositor sends one main_device event (unless + the client bound version 6 or above), 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. + + With version 6 and above, the compositor must always advertise at least + one tranche with the sampling flag set. @@ -463,7 +482,7 @@ - + This event advertises the main device that the server prefers to use when direct scan-out to the target device isn't possible. The @@ -488,6 +507,9 @@ 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. + + With version 6 and above, this event is no longer sent. Clients should + use a device with the sampling flag in the tranches instead. @@ -516,9 +538,9 @@ 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 + still be accessible from a device with the sampling flag, either through + direct import or a potentially more expensive fallback path. If the + buffer can't be directly imported for sampling, 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). @@ -564,19 +586,30 @@ - + + + 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. + + + + + The sampling flag describes that the compositor is able to efficiently + sample from buffers imported to the target device if the client + appropriately allocates a buffer. How to allocate a buffer that can be + efficiently sampled on the target device is implementation defined. + + - 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. + This event sets tranche-specific flags. This event is tied to a + preference tranche, see the tranche_done event. + With version 6 and above, the compositor must set at least one flag + in each tranche.