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

[Jani Nikula]

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.


>
> Thanks,
> Rafael
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Jani Nikula, Intel Open Source Technology Center