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]: 4aac98f8a6
[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>
This commit is contained in:
parent
d4af7d2519
commit
0a9886cc45
|
@ -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,
|
||||
|
|
Loading…
Reference in New Issue