[PATCH v7 3/5] drm: Document variable refresh properties

[Daniel Vetter]

On Mon, Nov 12, 2018 at 04:12:10PM +0000, Wentland, Harry wrote:
> On 2018-11-08 9:43 a.m., Nicholas Kazlauskas wrote:
> > These include the drm_connector 'vrr_capable' and the drm_crtc
> > 'vrr_enabled' properties.
> > 
> > Signed-off-by: Nicholas Kazlauskas <nicholas.kazlauskas at amd.com>
> > Cc: Harry Wentland <harry.wentland at amd.com>
> > Cc: Manasi Navare <manasi.d.navare at intel.com>
> > Cc: Pekka Paalanen <ppaalanen at gmail.com>
> > Cc: Ville Syrjälä <ville.syrjala at linux.intel.com>
> > Cc: Michel Dänzer <michel at daenzer.net>
> 
> Looks good. Whole series is
> Reviewed-by: Harry Wentland <harry.wentland at amd.com>
> 
> How are we with the userspace patches? We should probably hold off
> pushing the kernel patches until the userspace work is all reviewed.

Do some igts exist for this too? Especially for tricky pieces of uapi
having a non-vendor reference code somewhere would be good, aside from
testing and all that.
-Daniel

> 
> Harry
> 
> > ---
> >  Documentation/gpu/drm-kms.rst   |  7 ++++
> >  drivers/gpu/drm/drm_connector.c | 68 +++++++++++++++++++++++++++++++++
> >  2 files changed, 75 insertions(+)
> > 
> > diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> > index 4b1501b4835b..8da2a178cf85 100644
> > --- a/Documentation/gpu/drm-kms.rst
> > +++ b/Documentation/gpu/drm-kms.rst
> > @@ -575,6 +575,13 @@ Explicit Fencing Properties
> >  .. kernel-doc:: drivers/gpu/drm/drm_atomic_uapi.c
> >     :doc: explicit fencing properties
> >  
> > +
> > +Variable Refresh Properties
> > +---------------------------
> > +
> > +.. kernel-doc:: drivers/gpu/drm/drm_connector.c
> > +   :doc: Variable refresh properties
> > +
> >  Existing KMS Properties
> >  -----------------------
> >  
> > diff --git a/drivers/gpu/drm/drm_connector.c b/drivers/gpu/drm/drm_connector.c
> > index 49290060ab7b..0e4287461997 100644
> > --- a/drivers/gpu/drm/drm_connector.c
> > +++ b/drivers/gpu/drm/drm_connector.c
> > @@ -1255,6 +1255,74 @@ int drm_mode_create_scaling_mode_property(struct drm_device *dev)
> >  }
> >  EXPORT_SYMBOL(drm_mode_create_scaling_mode_property);
> >  
> > +/**
> > + * DOC: Variable refresh properties
> > + *
> > + * Variable refresh rate capable displays can dynamically adjust their
> > + * refresh rate by extending the duration of their vertical front porch
> > + * until page flip or timeout occurs. This can reduce or remove stuttering
> > + * and latency in scenarios where the page flip does not align with the
> > + * vblank interval.
> > + *
> > + * An example scenario would be an application flipping at a constant rate
> > + * of 48Hz on a 60Hz display. The page flip will frequently miss the vblank
> > + * interval and the same contents will be displayed twice. This can be
> > + * observed as stuttering for content with motion.
> > + *
> > + * If variable refresh rate was active on a display that supported a
> > + * variable refresh range from 35Hz to 60Hz no stuttering would be observable
> > + * for the example scenario. The minimum supported variable refresh rate of
> > + * 35Hz is below the page flip frequency and the vertical front porch can
> > + * be extended until the page flip occurs. The vblank interval will be
> > + * directly aligned to the page flip rate.
> > + *
> > + * Not all userspace content is suitable for use with variable refresh rate.
> > + * Large and frequent changes in vertical front porch duration may worsen
> > + * perceived stuttering for input sensitive applications.
> > + *
> > + * Panel brightness will also vary with vertical front porch duration. Some
> > + * panels may have noticeable differences in brightness between the minimum
> > + * vertical front porch duration and the maximum vertical front porch duration.
> > + * Large and frequent changes in vertical front porch duration may produce
> > + * observable flickering for such panels.
> > + *
> > + * Userspace control for variable refresh rate is supported via properties
> > + * on the &drm_connector and &drm_crtc objects.
> > + *
> > + * "vrr_capable":
> > + *	Optional &drm_connector boolean property that drivers should attach
> > + *	with drm_connector_attach_vrr_capable_property() on connectors that
> > + *	could support variable refresh rates. Drivers should update the
> > + *	property value by calling drm_connector_set_vrr_capable_property().
> > + *
> > + *	Absence of the property should indicate absence of support.
> > + *
> > + * "vrr_enabled":
> > + *	Default &drm_crtc boolean property that notifies the driver that the
> > + *	content on the CRTC is suitable for variable refresh rate presentation.
> > + *	The driver will take this property as a hint to enable variable
> > + *	refresh rate support if the receiver supports it, ie. if the
> > + *	"vrr_capable" property is true on the &drm_connector object. The
> > + *	vertical front porch duration will be extended until page-flip or
> > + *	timeout when enabled.
> > + *
> > + *	The minimum vertical front porch duration is defined as the vertical
> > + *	front porch duration for the current mode.
> > + *
> > + *	The maximum vertical front porch duration is greater than or equal to
> > + *	the minimum vertical front porch duration. The duration is derived
> > + *	from the minimum supported variable refresh rate for the connector.
> > + *
> > + *	The driver may place further restrictions within these minimum
> > + *	and maximum bounds.
> > + *
> > + *	The semantics for the vertical blank timestamp differ when
> > + *	variable refresh rate is active. The vertical blank timestamp
> > + *	is defined to be an estimate using the current mode's fixed
> > + *	refresh rate timings. The semantics for the page-flip event
> > + *	timestamp remain the same.
> > + */
> > +
> >  /**
> >   * drm_connector_attach_vrr_capable_property - creates the
> >   * vrr_capable property
> > 
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

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