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

[Rafael Antognolli]

On Wed, Sep 28, 2016 at 11:11:52AM +0300, Jani Nikula wrote:
> On Wed, 28 Sep 2016, Rafael Antognolli <rafael.antognolli at intel.com> wrote:
> > 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?
> 
> You're absolutely right. But you're missing the fix has already landed
> in drm-misc tree:
> 
> commit 226714dc7c6af6d0acee449eb2afce08d128edad
> Author: Daniel Vetter <daniel.vetter at ffwll.ch>
> Date:   Fri Sep 23 08:35:25 2016 +0200
> 
>     drm: Fix plane type uabi breakage
> 
> BR,
> Jani.

Oh, I was sure I had checked drm-intel-nightly too, but I clearly
didn't. Sorry for the noise.

Regards,
Rafael