Mesa (main): renderonly: write down usage rules
GitLab Mirror
gitlab-mirror at kemper.freedesktop.org
Mon Dec 20 12:14:38 UTC 2021
Module: Mesa
Branch: main
Commit: 0a9886cc45e5dd8ef8c041f490b79c6be4150881
URL: http://cgit.freedesktop.org/mesa/mesa/commit/?id=0a9886cc45e5dd8ef8c041f490b79c6be4150881
Author: Simon Ser <contact at emersion.fr>
Date: Tue Aug 17 18:43:45 2021 +0200
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 <contact at emersion.fr>
Reviewed-by: Lucas Stach <l.stach at pengutronix.de>
Reviewed-by: Daniel Stone <daniels at collabora.com>
[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: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/12418>
---
src/gallium/auxiliary/renderonly/renderonly.h | 15 +++++++++++++++
1 file changed, 15 insertions(+)
diff --git a/src/gallium/auxiliary/renderonly/renderonly.h b/src/gallium/auxiliary/renderonly/renderonly.h
index 0d08a16e30f..0eafbf548a9 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,
More information about the mesa-commit
mailing list