drm: Document variable refresh 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

-----------------------

}

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