[PATCH] drm: rework description of primary and cursor planes

[Daniel Vetter]

On Sun, Dec 06, 2020 at 04:34:15PM +0000, Simon Ser wrote:
> The previous wording could be understood by user-space evelopers as "a
> primary/cursor plane is only compatible with a single CRTC" [1].
> 
> Reword the planes description to make it clear the DRM-internal
> drm_crtc.primary and drm_crtc.cursor planes are for legacy uAPI.
> 
> [1]: https://github.com/swaywm/wlroots/pull/2333#discussion_r456788057
> 
> Signed-off-by: Simon Ser <contact at emersion.fr>
> Cc: Daniel Vetter <daniel at ffwll.ch>
> Cc: Pekka Paalanen <ppaalanen at gmail.com>
> ---
>  drivers/gpu/drm/drm_crtc.c  |  3 +++
>  drivers/gpu/drm/drm_plane.c | 16 +++++++++-------
>  2 files changed, 12 insertions(+), 7 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
> index 74090fc3aa55..c71b134d663a 100644
> --- a/drivers/gpu/drm/drm_crtc.c
> +++ b/drivers/gpu/drm/drm_crtc.c
> @@ -256,6 +256,9 @@ struct dma_fence *drm_crtc_create_fence(struct drm_crtc *crtc)
>   * planes). For really simple hardware which has only 1 plane look at
>   * drm_simple_display_pipe_init() instead.
>   *
> + * The @primary and @cursor planes are only relevant for legacy uAPI, see
> + * &drm_crtc.primary and &drm_crtc.cursor.
> + *
>   * Returns:
>   * Zero on success, error code on failure.
>   */
> diff --git a/drivers/gpu/drm/drm_plane.c b/drivers/gpu/drm/drm_plane.c
> index e6231947f987..7a5697bc9e04 100644
> --- a/drivers/gpu/drm/drm_plane.c
> +++ b/drivers/gpu/drm/drm_plane.c
> @@ -49,14 +49,16 @@
>   * &struct drm_plane (possibly as part of a larger structure) and registers it
>   * with a call to drm_universal_plane_init().
>   *
> - * Cursor and overlay planes are optional. All drivers should provide one
> - * primary plane per CRTC to avoid surprising userspace too much. See enum
> - * drm_plane_type for a more in-depth discussion of these special uapi-relevant
> - * plane types. Special planes are associated with their CRTC by calling
> - * drm_crtc_init_with_planes().
> - *
>   * The type of a plane is exposed in the immutable "type" enumeration property,
> - * which has one of the following values: "Overlay", "Primary", "Cursor".
> + * which has one of the following values: "Overlay", "Primary", "Cursor" (see
> + * enum drm_plane_type). A plane can be compatible with multiple CRTCs, see
> + * &drm_plane.possible_crtcs.
> + *
> + * Legacy uAPI doesn't expose the primary and cursor planes directly. DRM core
> + * relies on the driver to set the primary and optionally the cursor plane used
> + * for legacy IOCTLs. This is done by calling drm_crtc_init_with_planes(). All
> + * drivers should provide one primary plane per CRTC to avoid surprising legacy
> + * userspace too much.
>   */

Reviewed-by: Daniel Vetter <daniel.vetter at ffwll.ch>

I think maybe a follow up patch should document how userspace should
figure out how to line up the primary planes with the right crtcs (if it
wishes to know that information, it's not super useful aside from probably
good choice for a fullscreen fallback plane). See my reply on the old
thread.

And that patch should also add the code to drm_mode_config_validate() to
validate the possible_crtc masks for these. Something like

	num_primary = 0; num_cursor = 0;

	for_each_plane(plane) {
		if (plane->type == primary) {
			WARN_ON(!(plane->possible_crtcs & BIT(num_primary)));
			num_primary++;
		}

		/* same for cursor */
	}

	WARN_ON(num_primary != dev->mode_config.num_crtcs);
}

Cheers, Daniel

>  
>  static unsigned int drm_num_planes(struct drm_device *dev)
> -- 
> 2.29.2
> 
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch