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@emersion.fr>
Reviewed-by: Lucas Stach <l.stach@pengutronix.de>
Reviewed-by: Daniel Stone <daniels@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>

diff --git a/src/gallium/auxiliary/renderonly/renderonly.h b/src/gallium/auxiliary/renderonly/renderonly.h
index 0d08a16..0eafbf5 100644 (file)
--- 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,