From: Simon Ser Date: Tue, 17 Aug 2021 16:43:45 +0000 (+0200) Subject: renderonly: write down usage rules X-Git-Tag: upstream/22.3.5~14644 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=0a9886cc45e5dd8ef8c041f490b79c6be4150881;p=platform%2Fupstream%2Fmesa.git renderonly: write down usage rules The renderonly helpers are extremely easy to mis-use. Write down the expectations. I've seen *many* mistakes in the past, including: - Forgetting to create the scanout resource on import [1] [2], causing bugs such as [3]. - Assuming the scanout resource always exists [4]. - Returning a GEM handle valid for the driver's internal DRM FD, but invalid for the caller's DRM FD [5]. - Not implementing resource_get_param, breaking stride/offset/modifier queries when no scanout resource is available [6] [7]. Signed-off-by: Simon Ser Reviewed-by: Lucas Stach Reviewed-by: Daniel Stone [1]: https://gitlab.freedesktop.org/mesa/mesa/-/commit/4aac98f8a68b4c6407a5f41a91bfd7763f0607d7 [2]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12018 [3]: https://github.com/swaywm/wlroots/issues/2795 [4]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12081 [5]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12074 [6]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12362 [7]: https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12370 Part-of: --- diff --git a/src/gallium/auxiliary/renderonly/renderonly.h b/src/gallium/auxiliary/renderonly/renderonly.h index 0d08a16..0eafbf5 100644 --- a/src/gallium/auxiliary/renderonly/renderonly.h +++ b/src/gallium/auxiliary/renderonly/renderonly.h @@ -55,6 +55,21 @@ struct renderonly { * resource into the scanout hw. * - Make it easier for a gallium driver to detect if anything special needs * to be done in flush_resource(..) like a resolve to linear. + * + * When the screen has renderonly enabled, drivers need to follow these + * rules: + * - Create the scanout resource in resource_create and + * resource_create_with_modifiers if PIPE_BIND_SCANOUT is set. Drivers + * can fail if the scanout resource couldn't be created. + * - Try to import the scanout resource in resource_from_handle with + * renderonly_create_gpu_import_for_resource. Drivers MUST NOT fail if + * the scanout resource couldn't be created. + * - In a resource_get_handle call for WINSYS_HANDLE_TYPE_KMS, use + * renderonly_get_handle with the scanout resource, even if the scanout + * resource is NULL. Drivers MUST NOT return their own resource here, + * because the GEM handle will not be valid for the caller's DRM FD. + * - Implement resource_get_params for at least PIPE_RESOURCE_PARAM_STRIDE, + * PIPE_RESOURCE_PARAM_OFFSET and PIPE_RESOURCE_PARAM_MODIFIER. */ struct renderonly_scanout *(*create_for_resource)(struct pipe_resource *rsc, struct renderonly *ro,