A DRM API for adaptive sync and variable refresh rate support

Submitted by Nicholas Kazlauskas on Sept. 11, 2018, 4:13 p.m.

Details

Reviewer None
Submitted Sept. 11, 2018, 4:13 p.m.
Last Updated Nov. 8, 2018, 2:44 p.m.
Revision 7

Cover Letter(s)

Revision 1
      === Adaptive sync and variable refresh rate ===

Adaptive sync is part of the DisplayPort spec and allows for graphics adapters to drive displays with varying frame timings.

Variable refresh rate (VRR) is essentially the same, but defined for HDMI.

=== Use cases for variable refresh rate ===

Variable frame (flip) timings don't align well with fixed refresh rate displays. This results in stuttering, tearing and/or input lag. By adjusting the display refresh rate dynamically these issues can be reduced or eliminated.

However, not all content is suitable for dynamic refresh adaptation. Content that is flipped infrequently or at random intervals tends to fair poorly. Multiple clients trying to flip under the same screen can similarly interfere with prediction.

Userland needs a way to let the driver know when the content on the screen is suitable for variable refresh rate and if the user wishes to have the feature enabled.

=== DRM API to support variable refresh rates ===

This patch introduces a new API via atomic properties on the DRM connector and CRTC.

The connector has two new optional properties:

* bool variable_refresh_capable - set by the driver if the hardware is capable of supporting variable refresh tech

* bool variable_refresh_enabled - set by the user to enable variable refresh adjustment over the connector

The CRTC has one additional default property:

* bool variable_refresh - a content hint to the driver specifying that the CRTC contents are suitable for variable refresh adjustment

== Overview for DRM driver developers ===

Driver developers can attach the optional connector properties via drm_connector_attach_variable_refresh_properties on connectors that support variable refresh (typically DP or HDMI).

The variable_refresh_capable property should be managed as the output on the connector changes. The property is read only from userspace.

The variable_refresh_enabled property is intended to be a property controlled by userland as a global on/off switch for variable refresh technology. It should be checked before enabling variable refresh rate.

=== Overview for Userland developers ==

The variable_refresh property on the CRTC should be set to true when the CRTCs are suitable for variable refresh rate. In practice this is probably an application like a game - a single window that covers the whole CRTC surface and is the only client issuing flips.

To demonstrate the suitability of the API for variable refresh and dynamic adaptation there are additional patches using this API that implement adaptive variable refresh across kernel and userland projects:

- DRM (dri-devel)
- amdgpu DRM kernel driver (amd-gfx)
- xf86-video-amdgpu (amd-gfx)
- mesa (mesa-dev)

These patches enable adaptive variable refresh on X for AMD hardware provided that the user sets the variable_refresh_enabled property to true on supported connectors (ie. using xrandr --set-prop).

They have been tested on upstream userland under GNOME/KDE desktop environments under single and multi-monitor setups for a number of GL applications. Most games and benchmarks should work as expected provided that the compositor correctly unredirects the application's surface. KDE seems to have the best support for this with an explicit option to disable tearing support.

Full implementation details for these changes can be reviewed in their respective mailing lists.

=== Previous discussions ===

These patches are based upon feedback from patches and feedback from two previous threads on the subject which are linked below for reference:

https://lists.freedesktop.org/archives/amd-gfx/2018-April/021047.html
https://lists.freedesktop.org/archives/dri-devel/2017-October/155207.html

Nicholas Kazlauskas

Anthony Koo (1):
  drm/amd/display: Refactor FreeSync module

Harry Wentland (3):
  drm/amdgpu: fill in amdgpu_dm_remove_sink_from_freesync_module
  drm/amdgpu/display: add freesync drm properties
  drm/amdgpu: add freesync ioctl

Nicholas Kazlauskas (5):
  drm: Add variable refresh rate properties to DRM connector
  drm: Add variable refresh property to DRM CRTC
  drm/amd/display: Replace FreeSync props with DRM VRR props
  drm/amd/display: Drop FreeSync ioctl notification support
  drm/amdgpu: Drop unneeded freesync properties from amdpgu

 drivers/gpu/drm/amd/amdgpu/amdgpu.h           |    3 +
 drivers/gpu/drm/amd/amdgpu/amdgpu_display.c   |   16 +
 drivers/gpu/drm/amd/amdgpu/amdgpu_kms.c       |    3 +-
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c |  240 +--
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   17 +-
 .../display/amdgpu_dm/amdgpu_dm_mst_types.c   |   10 +-
 drivers/gpu/drm/amd/display/dc/core/dc.c      |   60 +-
 .../gpu/drm/amd/display/dc/core/dc_link_dp.c  |    3 +
 .../gpu/drm/amd/display/dc/core/dc_resource.c |  110 +-
 drivers/gpu/drm/amd/display/dc/dc_hw_types.h  |    6 -
 drivers/gpu/drm/amd/display/dc/dc_stream.h    |   29 +-
 drivers/gpu/drm/amd/display/dc/dc_types.h     |   22 +-
 .../display/dc/dce110/dce110_hw_sequencer.c   |   34 +-
 .../amd/display/dc/dcn10/dcn10_hw_sequencer.c |   27 +-
 .../drm/amd/display/include/set_mode_types.h  |   12 -
 .../amd/display/modules/freesync/freesync.c   | 1837 ++++++-----------
 .../amd/display/modules/inc/mod_freesync.h    |  144 +-
 drivers/gpu/drm/drm_atomic.c                  |   15 +
 drivers/gpu/drm/drm_atomic_helper.c           |    1 +
 drivers/gpu/drm/drm_connector.c               |   35 +
 drivers/gpu/drm/drm_crtc.c                    |    2 +
 drivers/gpu/drm/drm_mode_config.c             |    6 +
 include/drm/drm_connector.h                   |   27 +
 include/drm/drm_crtc.h                        |   13 +
 include/drm/drm_mode_config.h                 |    8 +
 include/uapi/drm/amdgpu_drm.h                 |   16 +
 26 files changed, 1026 insertions(+), 1670 deletions(-)
    
Revision 2
      These patches are part of a proposed new interface for supporting variable refresh rate via DRM properties.

=== Changes from v1 ===

For drm:

* The variable_refresh_capable property is now flagged as DRM_MODE_PROP_IMMUTABLE

For drm/gpu/amd/display:

* Patches no longer pull in IOCTL/FreeSync refactoring code
* FreeSync enable/disable behavior has been modified to reflect changes in userspace behavior from xf86-video-amdgpu and mesa

=== Adaptive sync and variable refresh rate ===

Adaptive sync is part of the DisplayPort spec and allows for graphics adapters to drive displays with varying frame timings.

Variable refresh rate (VRR) is essentially the same, but defined for HDMI.

=== Use cases for variable refresh rate ===

Variable frame (flip) timings don't align well with fixed refresh rate displays. This results in stuttering, tearing and/or input lag. By adjusting the display refresh rate dynamically these issues can be reduced or eliminated.

However, not all content is suitable for dynamic refresh adaptation. Content that is flipped infrequently or at random intervals tends to fair poorly. Multiple clients trying to flip under the same screen can similarly interfere with prediction.

Userland needs a way to let the driver know when the content on the screen is suitable for variable refresh rate and if the user wishes to have the feature enabled.

=== DRM API to support variable refresh rates ===

This patch introduces a new API via atomic properties on the DRM connector and CRTC.

The connector has two new optional properties:

* bool variable_refresh_capable - set by the driver if the hardware is capable of supporting variable refresh tech

* bool variable_refresh_enabled - set by the user to enable variable refresh adjustment over the connector

The CRTC has one additional default property:

* bool variable_refresh - a content hint to the driver specifying that the CRTC contents are suitable for variable refresh adjustment

== Overview for DRM driver developers ===

Driver developers can attach the optional connector properties via drm_connector_attach_variable_refresh_properties on connectors that support variable refresh (typically DP or HDMI).

The variable_refresh_capable property should be managed as the output on the connector changes. The property is read only from userspace.

The variable_refresh_enabled property is intended to be a property controlled by userland as a global on/off switch for variable refresh technology. It should be checked before enabling variable refresh rate.

=== Overview for Userland developers ==

The variable_refresh property on the CRTC should be set to true when the CRTCs are suitable for variable refresh rate. In practice this is probably an application like a game - a single window that covers the whole CRTC surface and is the only client issuing flips.

To demonstrate the suitability of the API for variable refresh and dynamic adaptation there are additional patches using this API that implement adaptive variable refresh across kernel and userland projects:

* DRM (dri-devel)
* amdgpu DRM kernel driver (amd-gfx)
* xf86-video-amdgpu (amd-gfx)
* mesa (mesa-dev)

These patches enable adaptive variable refresh on X for AMD hardware provided that the user sets the variable_refresh_enabled property to true on supported connectors (ie. using xrandr --set-prop).

The patches have been tested as working on upstream userland with the GNOME desktop environment under a single monitor setup. They also work on KDE in single monitor setup if the compositor is disabled.

The patches require that the application window can issue screen flips via the Present extension to xf86-video-amdgpu. Due to Present extension limitations some desktop environments and multi-monitor setups are currently not compatible.

Full implementation details for these changes can be reviewed in their respective mailing lists.

=== Previous discussions ===

These patches are based upon feedback from patches and feedback from two previous threads on the subject which are linked below for reference:

https://lists.freedesktop.org/archives/amd-gfx/2018-April/021047.html
https://lists.freedesktop.org/archives/dri-devel/2017-October/155207.html
https://lists.freedesktop.org/archives/dri-devel/2018-September/189404.html

Nicholas Kazlauskas

Nicholas Kazlauskas (3):
  drm: Add variable refresh rate properties to connector
  drm: Add variable refresh property to DRM CRTC
  drm/amd/display: Set FreeSync state using DRM VRR properties

 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 232 +++++++++---------
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   6 +-
 drivers/gpu/drm/drm_atomic_helper.c           |   1 +
 drivers/gpu/drm/drm_atomic_uapi.c             |  12 +
 drivers/gpu/drm/drm_connector.c               |  35 +++
 drivers/gpu/drm/drm_crtc.c                    |   2 +
 drivers/gpu/drm/drm_mode_config.c             |   6 +
 include/drm/drm_connector.h                   |  27 ++
 include/drm/drm_crtc.h                        |  13 +
 include/drm/drm_mode_config.h                 |   8 +
 10 files changed, 225 insertions(+), 117 deletions(-)
    
Revision 3
      These patches are part of a proposed new interface for supporting variable refresh rate via DRM properties.

=== Changes from v2 ===

The interface has changed substantially from the last revision and the cover letter has been updated accordingly.

drm changes:

* Most "variable_refresh" prefixes in code have been shortened to just "vrr". This was motivated after changes to the interface had function names close to 80 characters long. Comments from the mailing list were already shortening these in discussion as well.
* Documentation for "Variable Refresh" has been added to the KMS properties subsection for DRM driver developers.
* The drm_connector property "variable_refresh_capable" has been renamed to "vrr_capable".
* The drm_crtc property "variable_refresh" has been been renamed "vrr_enabled" to better reflect its usage.
* The drm_connector "variable_refresh_enabled" property has been removed. Managing this is now up to userspace when it sets "vrr_enabled".
* The "vrr_capable" property no longer has any state in drm_connector_state associated with it. The value can now be updated with the drm_connector_set_vrr_capable_property() function. This better matches the immutable flag on the property.
* The "variable_refresh_changed" flag has been removed from atomic helpers based on feedback from the mailing list and updated interface usage in the amd kernel driver.

amd/display changes:

* Updated interface usage based on the new properties
* Updated VRR infopacket handling based on new xf86-video-amdgpu usage

=== Adaptive sync and variable refresh rate ===

Adaptive sync is part of the DisplayPort specification and allows for graphics adapters to drive displays with varying frame timings.

Variable refresh rate (VRR) is essentially the same, but defined for HDMI.

=== Use cases for variable refresh rate ===

Variable frame (flip) timings don't align well with fixed refresh rate displays. This results in stuttering, tearing and/or input lag. By adjusting the display refresh rate dynamically these issues can be reduced or eliminated.

However, not all content is suitable for dynamic refresh adaptation. The user may experience "flickering" from differences in panel luminance at different refresh rates. Content that flips at an infrequent rate or demand is more likely to cause large changes in refresh rate that result in flickering.

Userland needs a way to let the driver know when the screen content is suitable for variable refresh rates.

=== DRM API to support variable refresh rates ===

This patch introduces a new API via atomic properties on the DRM connector and CRTC.

The drm_connector has one new optional boolean property:

* bool vrr_capable - set by the driver if the hardware is capable of supporting variable refresh rates

The drm_crtc has one new default boolean property:

* bool vrr_enabled - set by userspace indicating that variable refresh rate should be enabled

== Overview for DRM driver developers ===

Driver developers can attach the "vrr_capable" property by calling drm_connector_attach_vrr_capable_property(). This should be done on connectors that could be capable of supporting variable refresh rates (such as DP or HDMI).

The "vrr_capable" can then be updated accordingly by calling drm_connector_set_vrr_capable_property().

The "vrr_enabled" property can be checked from the drm_crtc_state object.

=== Overview for Userland developers ==

The "vrr_enabled" property on the CRTC should be set to true when the CRTC is suitable for variable refresh rates.

To demonstrate the suitability of the API for variable refresh and dynamic adaptation there are additional patches using this API that implement adaptive variable refresh across kernel and userland projects:

* DRM (dri-devel)
* amdgpu DRM kernel driver (amd-gfx)
* xf86-video-amdgpu (https://gitlab.freedesktop.org/xorg/driver/xf86-video-amdgpu)
* mesa (mesa-dev)

These patches enable adaptive variable refresh on X for AMD hardware. Support for variable refresh is disabled by default in xf86-video-amdgpu and will require additional user configuration.

The patches have been tested as working on upstream userland with the GNOME desktop environment under a single monitor setup. They also work on KDE in a single monitor setup with the compositor disabled.

The patches require that suitable applications flip via the Present extension to xf86-video-amdgpu for the entire Screen. Some compositors may interfere with this if they are unable to unredirect the window.

Full implementation details for these changes can be reviewed in their respective mailing lists and the xf86-video-amdgpu GitLab.

=== Previous discussions ===

These patches are based upon feedback from previous threads on the subject. These are linked below for reference:

https://lists.freedesktop.org/archives/amd-gfx/2018-April/021047.html
https://lists.freedesktop.org/archives/dri-devel/2017-October/155207.html
https://lists.freedesktop.org/archives/dri-devel/2018-September/189404.html
https://lists.freedesktop.org/archives/dri-devel/2018-September/190910.html

Nicholas Kazlauskas (4):
  drm: Add vrr_capable property to the drm connector
  drm: Add vrr_enabled property to drm CRTC
  drm: Document variable refresh properties
  drm/amd/display: Set FreeSync state using drm VRR properties

 Documentation/gpu/drm-kms.rst                 |   7 +
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 255 +++++++++---------
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   7 +-
 drivers/gpu/drm/drm_atomic_uapi.c             |   4 +
 drivers/gpu/drm/drm_connector.c               |  73 +++++
 drivers/gpu/drm/drm_crtc.c                    |   2 +
 drivers/gpu/drm/drm_mode_config.c             |   6 +
 include/drm/drm_connector.h                   |  15 ++
 include/drm/drm_crtc.h                        |   9 +
 include/drm/drm_mode_config.h                 |   5 +
 10 files changed, 259 insertions(+), 124 deletions(-)
    
Revision 4
      These patches are part of a proposed new interface for supporting variable refresh rate via DRM properties.

=== Changes from v3 ===

drm changes:

* Docstring and formatting fixes

amd/display changes:

* Updated commit message and debug statements

=== Changes from v2 ===

The interface has changed substantially from the last revision and the cover letter has been updated accordingly.

drm changes:

* Most "variable_refresh" prefixes in code have been shortened to just "vrr". This was motivated after changes to the interface had function names close to 80 characters long. Comments from the mailing list were already shortening these in discussion as well.
* Documentation for "Variable Refresh" has been added to the KMS properties subsection for DRM driver developers.
* The drm_connector property "variable_refresh_capable" has been renamed to "vrr_capable".
* The drm_crtc property "variable_refresh" has been been renamed "vrr_enabled" to better reflect its usage.
* The drm_connector "variable_refresh_enabled" property has been removed. Managing this is now up to userspace when it sets "vrr_enabled".
* The "vrr_capable" property no longer has any state in drm_connector_state associated with it. The value can now be updated with the drm_connector_set_vrr_capable_property() function. This better matches the immutable flag on the property.
* The "variable_refresh_changed" flag has been removed from atomic helpers based on feedback from the mailing list and updated interface usage in the amd kernel driver.

amd/display changes:

* Updated interface usage based on the new properties
* Updated VRR infopacket handling based on new xf86-video-amdgpu usage

=== Adaptive sync and variable refresh rate ===

Adaptive sync is part of the DisplayPort specification and allows for graphics adapters to drive displays with varying frame timings.

Variable refresh rate (VRR) is essentially the same, but defined for HDMI.

=== Use cases for variable refresh rate ===

Variable frame (flip) timings don't align well with fixed refresh rate displays. This results in stuttering, tearing and/or input lag. By adjusting the display refresh rate dynamically these issues can be reduced or eliminated.

However, not all content is suitable for dynamic refresh adaptation. The user may experience "flickering" from differences in panel luminance at different refresh rates. Content that flips at an infrequent rate or demand is more likely to cause large changes in refresh rate that result in flickering.

Userland needs a way to let the driver know when the screen content is suitable for variable refresh rates.

=== DRM API to support variable refresh rates ===

This patch introduces a new API via atomic properties on the DRM connector and CRTC.

The drm_connector has one new optional boolean property:

* bool vrr_capable - set by the driver if the hardware is capable of supporting variable refresh rates

The drm_crtc has one new default boolean property:

* bool vrr_enabled - set by userspace indicating that variable refresh rate should be enabled

== Overview for DRM driver developers ===

Driver developers can attach the "vrr_capable" property by calling drm_connector_attach_vrr_capable_property(). This should be done on connectors that could be capable of supporting variable refresh rates (such as DP or HDMI).

The "vrr_capable" can then be updated accordingly by calling drm_connector_set_vrr_capable_property().

The "vrr_enabled" property can be checked from the drm_crtc_state object.

=== Overview for Userland developers ==

The "vrr_enabled" property on the CRTC should be set to true when the CRTC is suitable for variable refresh rates.

To demonstrate the suitability of the API for variable refresh and dynamic adaptation there are additional patches using this API that implement adaptive variable refresh across kernel and userland projects:

* DRM (dri-devel)
* amdgpu DRM kernel driver (amd-gfx)
* xf86-video-amdgpu (https://gitlab.freedesktop.org/xorg/driver/xf86-video-amdgpu)
* mesa (mesa-dev)

These patches enable adaptive variable refresh on X for AMD hardware. Support for variable refresh is disabled by default in xf86-video-amdgpu and will require additional user configuration.

The patches have been tested as working on upstream userland with the GNOME desktop environment under a single monitor setup. They also work on KDE in a single monitor setup with the compositor disabled.

The patches require that suitable applications flip via the Present extension to xf86-video-amdgpu for the entire Screen. Some compositors may interfere with this if they are unable to unredirect the window.

Full implementation details for these changes can be reviewed in their respective mailing lists and the xf86-video-amdgpu GitLab.

=== Previous discussions ===

These patches are based upon feedback from previous threads on the subject. These are linked below for reference:

https://lists.freedesktop.org/archives/amd-gfx/2018-April/021047.html
https://lists.freedesktop.org/archives/dri-devel/2017-October/155207.html
https://lists.freedesktop.org/archives/dri-devel/2018-September/189404.htm
https://lists.freedesktop.org/archives/dri-devel/2018-September/190910.html
https://lists.freedesktop.org/archives/dri-devel/2018-October/192211.html

Nicholas Kazlauskas (4):
  drm: Add vrr_capable property to the drm connector
  drm: Add vrr_enabled property to drm CRTC
  drm: Document variable refresh properties
  drm/amd/display: Set FreeSync state using drm VRR properties

 Documentation/gpu/drm-kms.rst                 |   7 +
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 255 +++++++++---------
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   7 +-
 drivers/gpu/drm/drm_atomic_uapi.c             |   4 +
 drivers/gpu/drm/drm_connector.c               |  71 +++++
 drivers/gpu/drm/drm_crtc.c                    |   2 +
 drivers/gpu/drm/drm_mode_config.c             |   6 +
 include/drm/drm_connector.h                   |  15 ++
 include/drm/drm_crtc.h                        |   9 +
 include/drm/drm_mode_config.h                 |   5 +
 10 files changed, 257 insertions(+), 124 deletions(-)
    
Revision 5
      These patches are part of a proposed new interface for supporting variable refresh rate via DRM properties.

=== Changes from v4 ===

amd changes:

* Removed unused FreeSync functions from amdgpu

=== Changes from v3 ===

drm changes:

* Docstring and formatting fixes

amd/display changes:

* Updated commit message and debug statements

=== Changes from v2 ===

The interface has changed substantially from the last revision and the cover letter has been updated accordingly.

drm changes:

* Most "variable_refresh" prefixes in code have been shortened to just "vrr". This was motivated after changes to the interface had function names close to 80 characters long. Comments from the mailing list were already shortening these in discussion as well.
* Documentation for "Variable Refresh" has been added to the KMS properties subsection for DRM driver developers.
* The drm_connector property "variable_refresh_capable" has been renamed to "vrr_capable".
* The drm_crtc property "variable_refresh" has been been renamed "vrr_enabled" to better reflect its usage.
* The drm_connector "variable_refresh_enabled" property has been removed. Managing this is now up to userspace when it sets "vrr_enabled".
* The "vrr_capable" property no longer has any state in drm_connector_state associated with it. The value can now be updated with the drm_connector_set_vrr_capable_property() function. This better matches the immutable flag on the property.
* The "variable_refresh_changed" flag has been removed from atomic helpers based on feedback from the mailing list and updated interface usage in the amd kernel driver.

amd/display changes:

* Updated interface usage based on the new properties
* Updated VRR infopacket handling based on new xf86-video-amdgpu usage

=== Adaptive sync and variable refresh rate ===

Adaptive sync is part of the DisplayPort specification and allows for graphics adapters to drive displays with varying frame timings.

Variable refresh rate (VRR) is essentially the same, but defined for HDMI.

=== Use cases for variable refresh rate ===

Variable frame (flip) timings don't align well with fixed refresh rate displays. This results in stuttering, tearing and/or input lag. By adjusting the display refresh rate dynamically these issues can be reduced or eliminated.

However, not all content is suitable for dynamic refresh adaptation. The user may experience "flickering" from differences in panel luminance at different refresh rates. Content that flips at an infrequent rate or demand is more likely to cause large changes in refresh rate that result in flickering.

Userland needs a way to let the driver know when the screen content is suitable for variable refresh rates.

=== DRM API to support variable refresh rates ===

This patch introduces a new API via atomic properties on the DRM connector and CRTC.

The drm_connector has one new optional boolean property:

* bool vrr_capable - set by the driver if the hardware is capable of supporting variable refresh rates

The drm_crtc has one new default boolean property:

* bool vrr_enabled - set by userspace indicating that variable refresh rate should be enabled

== Overview for DRM driver developers ===

Driver developers can attach the "vrr_capable" property by calling drm_connector_attach_vrr_capable_property(). This should be done on connectors that could be capable of supporting variable refresh rates (such as DP or HDMI).

The "vrr_capable" can then be updated accordingly by calling drm_connector_set_vrr_capable_property().

The "vrr_enabled" property can be checked from the drm_crtc_state object.

=== Overview for Userland developers ==

The "vrr_enabled" property on the CRTC should be set to true when the CRTC is suitable for variable refresh rates.

To demonstrate the suitability of the API for variable refresh and dynamic adaptation there are additional patches using this API that implement adaptive variable refresh across kernel and userland projects:

* DRM (dri-devel)
* amdgpu DRM kernel driver (amd-gfx)
* xf86-video-amdgpu (https://gitlab.freedesktop.org/xorg/driver/xf86-video-amdgpu)
* mesa (mesa-dev)

These patches enable adaptive variable refresh on X for AMD hardware. Support for variable refresh is disabled by default in xf86-video-amdgpu and will require additional user configuration.

The patches have been tested as working on upstream userland with the GNOME desktop environment under a single monitor setup. They also work on KDE in a single monitor setup with the compositor disabled.

The patches require that suitable applications flip via the Present extension to xf86-video-amdgpu for the entire Screen. Some compositors may interfere with this if they are unable to unredirect the window.

Full implementation details for these changes can be reviewed in their respective mailing lists and the xf86-video-amdgpu GitLab.

=== Previous discussions ===

These patches are based upon feedback from previous threads on the subject. These are linked below for reference:

https://lists.freedesktop.org/archives/amd-gfx/2018-April/021047.html
https://lists.freedesktop.org/archives/dri-devel/2017-October/155207.html
https://lists.freedesktop.org/archives/dri-devel/2018-September/189404.htm
https://lists.freedesktop.org/archives/dri-devel/2018-September/190910.html
https://lists.freedesktop.org/archives/dri-devel/2018-October/192211.html
https://lists.freedesktop.org/archives/dri-devel/2018-October/192874.html

Nicholas Kazlauskas (4):
  drm: Add vrr_capable property to the drm connector
  drm: Add vrr_enabled property to drm CRTC
  drm: Document variable refresh properties
  drm/amdgpu: Set FreeSync state using drm VRR properties

 Documentation/gpu/drm-kms.rst                 |   7 +
 drivers/gpu/drm/amd/amdgpu/amdgpu_mode.h      |   7 -
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 255 +++++++++---------
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   7 +-
 drivers/gpu/drm/drm_atomic_uapi.c             |   4 +
 drivers/gpu/drm/drm_connector.c               |  71 +++++
 drivers/gpu/drm/drm_crtc.c                    |   2 +
 drivers/gpu/drm/drm_mode_config.c             |   6 +
 include/drm/drm_connector.h                   |  15 ++
 include/drm/drm_crtc.h                        |   9 +
 include/drm/drm_mode_config.h                 |   5 +
 11 files changed, 257 insertions(+), 131 deletions(-)
    
Revision 6
      These patches are part of a proposed new interface for supporting variable refresh rate via DRM properties.

=== Changes from v5 ===

drm changes:

* Updated documentation to define userspace expectations when variable refresh rate is enabled

amd changes:

* Added patch to fix vblank timestamp calculations when vpos > vtotal

=== Changes from v4 ===

amd changes:

* Removed unused FreeSync functions from amdgpu

=== Changes from v3 ===

drm changes:

* Docstring and formatting fixes

amd/display changes:

* Updated commit message and debug statements

=== Changes from v2 ===

The interface has changed substantially from the last revision and the cover letter has been updated accordingly.

drm changes:

* Most "variable_refresh" prefixes in code have been shortened to just "vrr". This was motivated after changes to the interface had function names close to 80 characters long. Comments from the mailing list were already shortening these in discussion as well.
* Documentation for "Variable Refresh" has been added to the KMS properties subsection for DRM driver developers.
* The drm_connector property "variable_refresh_capable" has been renamed to "vrr_capable".
* The drm_crtc property "variable_refresh" has been been renamed "vrr_enabled" to better reflect its usage.
* The drm_connector "variable_refresh_enabled" property has been removed. Managing this is now up to userspace when it sets "vrr_enabled".
* The "vrr_capable" property no longer has any state in drm_connector_state associated with it. The value can now be updated with the drm_connector_set_vrr_capable_property() function. This better matches the immutable flag on the property.
* The "variable_refresh_changed" flag has been removed from atomic helpers based on feedback from the mailing list and updated interface usage in the amd kernel driver.

amd/display changes:

* Updated interface usage based on the new properties
* Updated VRR infopacket handling based on new xf86-video-amdgpu usage

=== Adaptive sync and variable refresh rate ===

Adaptive sync is part of the DisplayPort specification and allows for graphics adapters to drive displays with varying frame timings.

Variable refresh rate (VRR) is essentially the same, but defined for HDMI.

=== Use cases for variable refresh rate ===

Variable frame (flip) timings don't align well with fixed refresh rate displays. This results in stuttering, tearing and/or input lag. By adjusting the display refresh rate dynamically these issues can be reduced or eliminated.

However, not all content is suitable for dynamic refresh adaptation. The user may experience "flickering" from differences in panel luminance at different refresh rates. Content that flips at an infrequent rate or demand is more likely to cause large changes in refresh rate that result in flickering.

Userland needs a way to let the driver know when the screen content is suitable for variable refresh rates.

=== DRM API to support variable refresh rates ===

This patch introduces a new API via atomic properties on the DRM connector and CRTC.

The drm_connector has one new optional boolean property:

* bool vrr_capable - set by the driver if the hardware is capable of supporting variable refresh rates

The drm_crtc has one new default boolean property:

* bool vrr_enabled - set by userspace indicating that variable refresh rate should be enabled

== Overview for DRM driver developers ===

Driver developers can attach the "vrr_capable" property by calling drm_connector_attach_vrr_capable_property(). This should be done on connectors that could be capable of supporting variable refresh rates (such as DP or HDMI).

The "vrr_capable" can then be updated accordingly by calling drm_connector_set_vrr_capable_property().

The "vrr_enabled" property can be checked from the drm_crtc_state object.

=== Overview for Userland developers ==

The "vrr_enabled" property on the CRTC should be set to true when the CRTC is suitable for variable refresh rates.

To demonstrate the suitability of the API for variable refresh and dynamic adaptation there are additional patches using this API that implement adaptive variable refresh across kernel and userland projects:

* DRM (dri-devel)
* amdgpu DRM kernel driver (amd-gfx)
* xf86-video-amdgpu (https://gitlab.freedesktop.org/xorg/driver/xf86-video-amdgpu)
* mesa (mesa-dev)

These patches enable adaptive variable refresh on X for AMD hardware. Support for variable refresh is disabled by default in xf86-video-amdgpu and will require additional user configuration.

The patches have been tested as working on upstream userland with the GNOME desktop environment under a single monitor setup. They also work on KDE in a single monitor setup with the compositor disabled.

The patches require that suitable applications flip via the Present extension to xf86-video-amdgpu for the entire Screen. Some compositors may interfere with this if they are unable to unredirect the window.

Full implementation details for these changes can be reviewed in their respective mailing lists and the xf86-video-amdgpu GitLab.

=== Previous discussions ===

These patches are based upon feedback from previous threads on the subject. These are linked below for reference:

https://lists.freedesktop.org/archives/amd-gfx/2018-April/021047.html
https://lists.freedesktop.org/archives/dri-devel/2017-October/155207.html
https://lists.freedesktop.org/archives/dri-devel/2018-September/189404.htm
https://lists.freedesktop.org/archives/dri-devel/2018-September/190910.html
https://lists.freedesktop.org/archives/dri-devel/2018-October/192211.html
https://lists.freedesktop.org/archives/dri-devel/2018-October/192874.html

Nicholas Kazlauskas (5):
  drm: Add vrr_capable property to the drm connector
  drm: Add vrr_enabled property to drm CRTC
  drm: Document variable refresh properties
  drm/amdgpu: Correct get_crtc_scanoutpos behavior when vpos >= vtotal
  drm/amdgpu: Set FreeSync state using drm VRR properties

 Documentation/gpu/drm-kms.rst                 |   7 +
 drivers/gpu/drm/amd/amdgpu/amdgpu_display.c   |   7 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_mode.h      |   7 -
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 255 +++++++++---------
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   7 +-
 drivers/gpu/drm/drm_atomic_uapi.c             |   4 +
 drivers/gpu/drm/drm_connector.c               | 110 ++++++++
 drivers/gpu/drm/drm_crtc.c                    |   2 +
 drivers/gpu/drm/drm_mode_config.c             |   6 +
 include/drm/drm_connector.h                   |  15 ++
 include/drm/drm_crtc.h                        |   9 +
 include/drm/drm_mode_config.h                 |   5 +
 12 files changed, 302 insertions(+), 132 deletions(-)
    
Revision 7
      These patches are part of a proposed new interface for supporting variable refresh rate via DRM properties.

=== Changes from v6 ===

drm changes:

* Updated documentation typos, added more information about potential issues with luminance changes

=== Changes from v5 ===

drm changes:

* Updated documentation to define userspace expectations when variable refresh rate is enabled

amd changes:

* Added patch to fix vblank timestamp calculations when vpos > vtotal

=== Changes from v4 ===

amd changes:

* Removed unused FreeSync functions from amdgpu

=== Changes from v3 ===

drm changes:

* Docstring and formatting fixes

amd/display changes:

* Updated commit message and debug statements

=== Changes from v2 ===

The interface has changed substantially from the last revision and the cover letter has been updated accordingly.

drm changes:

* Most "variable_refresh" prefixes in code have been shortened to just "vrr". This was motivated after changes to the interface had function names close to 80 characters long. Comments from the mailing list were already shortening these in discussion as well.
* Documentation for "Variable Refresh" has been added to the KMS properties subsection for DRM driver developers.
* The drm_connector property "variable_refresh_capable" has been renamed to "vrr_capable".
* The drm_crtc property "variable_refresh" has been been renamed "vrr_enabled" to better reflect its usage.
* The drm_connector "variable_refresh_enabled" property has been removed. Managing this is now up to userspace when it sets "vrr_enabled".
* The "vrr_capable" property no longer has any state in drm_connector_state associated with it. The value can now be updated with the drm_connector_set_vrr_capable_property() function. This better matches the immutable flag on the property.
* The "variable_refresh_changed" flag has been removed from atomic helpers based on feedback from the mailing list and updated interface usage in the amd kernel driver.

amd/display changes:

* Updated interface usage based on the new properties
* Updated VRR infopacket handling based on new xf86-video-amdgpu usage

=== Adaptive sync and variable refresh rate ===

Adaptive sync is part of the DisplayPort specification and allows for graphics adapters to drive displays with varying frame timings.

Variable refresh rate (VRR) is essentially the same, but defined for HDMI.

=== Use cases for variable refresh rate ===

Variable frame (flip) timings don't align well with fixed refresh rate displays. This results in stuttering, tearing and/or input lag. By adjusting the display refresh rate dynamically these issues can be reduced or eliminated.

However, not all content is suitable for dynamic refresh adaptation. The user may experience "flickering" from differences in panel luminance at different refresh rates. Content that flips at an infrequent rate or demand is more likely to cause large changes in refresh rate that result in flickering.

Userland needs a way to let the driver know when the screen content is suitable for variable refresh rates.

=== DRM API to support variable refresh rates ===

This patch introduces a new API via atomic properties on the DRM connector and CRTC.

The drm_connector has one new optional boolean property:

* bool vrr_capable - set by the driver if the hardware is capable of supporting variable refresh rates

The drm_crtc has one new default boolean property:

* bool vrr_enabled - set by userspace indicating that variable refresh rate should be enabled

== Overview for DRM driver developers ===

Driver developers can attach the "vrr_capable" property by calling drm_connector_attach_vrr_capable_property(). This should be done on connectors that could be capable of supporting variable refresh rates (such as DP or HDMI).

The "vrr_capable" can then be updated accordingly by calling drm_connector_set_vrr_capable_property().

The "vrr_enabled" property can be checked from the drm_crtc_state object.

=== Overview for Userland developers ==

The "vrr_enabled" property on the CRTC should be set to true when the CRTC is suitable for variable refresh rates.

To demonstrate the suitability of the API for variable refresh and dynamic adaptation there are additional patches using this API that implement adaptive variable refresh across kernel and userland projects:

* DRM (dri-devel)
* amdgpu DRM kernel driver (amd-gfx)
* xf86-video-amdgpu (https://gitlab.freedesktop.org/xorg/driver/xf86-video-amdgpu)
* mesa (mesa-dev)

These patches enable adaptive variable refresh on X for AMD hardware. Support for variable refresh is disabled by default in xf86-video-amdgpu and will require additional user configuration.

The patches have been tested as working on upstream userland with the GNOME desktop environment under a single monitor setup. They also work on KDE in a single monitor setup with the compositor disabled.

The patches require that suitable applications flip via the Present extension to xf86-video-amdgpu for the entire Screen. Some compositors may interfere with this if they are unable to unredirect the window.

Full implementation details for these changes can be reviewed in their respective mailing lists and the xf86-video-amdgpu GitLab.

=== Previous discussions ===

These patches are based upon feedback from previous threads on the subject. These are linked below for reference:

https://lists.freedesktop.org/archives/amd-gfx/2018-April/021047.html
https://lists.freedesktop.org/archives/dri-devel/2017-October/155207.html
https://lists.freedesktop.org/archives/dri-devel/2018-September/189404.htm
https://lists.freedesktop.org/archives/dri-devel/2018-September/190910.html
https://lists.freedesktop.org/archives/dri-devel/2018-October/192211.html
https://lists.freedesktop.org/archives/dri-devel/2018-October/192874.html

Nicholas Kazlauskas (5):
  drm: Add vrr_capable property to the drm connector
  drm: Add vrr_enabled property to drm CRTC
  drm: Document variable refresh properties
  drm/amdgpu: Correct get_crtc_scanoutpos behavior when vpos >= vtotal
  drm/amdgpu: Set FreeSync state using drm VRR properties

 Documentation/gpu/drm-kms.rst                 |   7 +
 drivers/gpu/drm/amd/amdgpu/amdgpu_display.c   |   7 +-
 drivers/gpu/drm/amd/amdgpu/amdgpu_mode.h      |   7 -
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.c | 255 +++++++++---------
 .../gpu/drm/amd/display/amdgpu_dm/amdgpu_dm.h |   7 +-
 drivers/gpu/drm/drm_atomic_uapi.c             |   4 +
 drivers/gpu/drm/drm_connector.c               | 117 ++++++++
 drivers/gpu/drm/drm_crtc.c                    |   2 +
 drivers/gpu/drm/drm_mode_config.c             |   6 +
 include/drm/drm_connector.h                   |  15 ++
 include/drm/drm_crtc.h                        |   9 +
 include/drm/drm_mode_config.h                 |   5 +
 12 files changed, 309 insertions(+), 132 deletions(-)
    

Revisions