[PATCH 2/7] drm/doc: Polish for drm_plane.[hc]

[Rafael Antognolli]

Hi Daniel,

On Wed, Sep 21, 2016 at 10:59:25AM +0200, Daniel Vetter wrote:
> diff --git a/include/drm/drm_plane.h b/include/drm/drm_plane.h
> index 1407715736a5..256219bfd07b 100644
> --- a/include/drm/drm_plane.h
> +++ b/include/drm/drm_plane.h
> @@ -319,10 +319,48 @@ struct drm_plane_funcs {
>  	void (*early_unregister)(struct drm_plane *plane);
>  };
>  
> +/**
> + * enum drm_plane_type - uapi plane type enumeration
> + *
> + * For historical reasons not all planes are made the same. This enumeration is
> + * used to tell the different types of planes apart to implement the different
> + * uapi semantics for them. For userspace which is universal plane aware and
> + * which is using that atomic IOCTL there's no difference between these planes
> + * (beyong what the driver and hardware can support of course).
> + *
> + * For compatibility with legacy userspace, only overlay planes are made
> + * available to userspace by default. Userspace clients may set the
> + * DRM_CLIENT_CAP_UNIVERSAL_PLANES client capability bit to indicate that they
> + * wish to receive a universal plane list containing all plane types. See also
> + * drm_for_each_legacy_plane().
> + */
>  enum drm_plane_type {
> -	DRM_PLANE_TYPE_OVERLAY,
> +	/**
> +	 * @DRM_PLANE_TYPE_PRIMARY:
> +	 *
> +	 * Primary planes represent a "main" plane for a CRTC.  Primary planes
> +	 * are the planes operated upon by CRTC modesetting and flipping
> +	 * operations described in the page_flip and set_config hooks in struct
> +	 * &drm_crtc_funcs.
> +	 */
>  	DRM_PLANE_TYPE_PRIMARY,
> +
> +	/**
> +	 * @DRM_PLANE_TYPE_CURSOR:
> +	 *
> +	 * Cursor planes represent a "cursor" plane for a CRTC.  Cursor planes
> +	 * are the planes operated upon by the DRM_IOCTL_MODE_CURSOR and
> +	 * DRM_IOCTL_MODE_CURSOR2 IOCTLs.
> +	 */
>  	DRM_PLANE_TYPE_CURSOR,
> +
> +	/**
> +	 * @DRM_PLANE_TYPE_OVERLAY:
> +	 *
> +	 * Overlay planes represent all non-primary, non-cursor planes. Some
> +	 * drivers refer to these types of planes as "sprites" internally.
> +	 */
> +	DRM_PLANE_TYPE_OVERLAY,
>  };

This is changing the order (and consequently the values) of these enums.
But it is not updated in libdrm. I noticed this is causing an issue when
playing with robclark's version of kmscube (branch atomic):

https://github.com/robclark/kmscube/tree/atomic

It looks like IGT also uses this macro from libdrm:

$ git grep -n DRM_PLANE_TYPE_PRIMARY
lib/igt_kms.c:1398:                     case DRM_PLANE_TYPE_PRIMARY:
tests/kms_frontbuffer_tracking.c:2302:              drm.plane_types[i] == DRM_PLANE_TYPE_PRIMARY)
tests/kms_frontbuffer_tracking.c:2602:              drm.plane_types[i] == DRM_PLANE_TYPE_PRIMARY) {
tests/kms_frontbuffer_tracking.c:2741:              drm.plane_types[i] == DRM_PLANE_TYPE_PRIMARY)

Anyway, should we update it on libdrm, bring the order back to its
original values, or something else? Or am I missing something?

Thanks,
Rafael