feat[DSS7]: Document SELF_REFRESH and ALWAYS_ON_DISPLAY properties

source/linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7.rst

@@ -508,6 +508,12 @@
 +--------------------+----------+------------------------------------------------------------------------------------------------------+
 | GAMMA_LUT_SIZE     | crtc     | Number of elements in gammma lookup table.                                                           |
 +--------------------+----------+------------------------------------------------------------------------------------------------------+
+| SELF_REFRESH       | plane    | Boolean property. When set, plays the last displayed frame in a loop from the DSS internal buffer;   |
+|                    |          | new framebuffers submitted by userspace are ignored until the property is cleared.                   |
++--------------------+----------+------------------------------------------------------------------------------------------------------+
+| ALWAYS_ON_DISPLAY  | crtc     | Boolean property. When set, keeps the video port, along with its associated bridges and PHYs,        |
+|                    |          | powered on even after the last DRM client exits.                                                     |
++--------------------+----------+------------------------------------------------------------------------------------------------------+
 
 .. _testing_tidss_properties:
 
@@ -770,6 +776,130 @@
 *  `<https://www.w3.org/TR/PNG-GammaAppendix.html>`__
 *  `<https://www.benq.com/en-us/knowledge-center/knowledge/gamma-monitor.html>`__
 
+.. rubric:: Self Refresh
+
+Self refresh plays last displayed frame in a loop using DSS internal buffer.
+
+The ``SELF_REFRESH`` plane property is a boolean property. When set to 1, the DSS
+hardware plays the last frame that was submitted to the plane in a loop from its
+internal buffer. Any new framebuffer submitted by userspace while the property
+is set is silently ignored; the display resumes normal operation, taking new
+framebuffers into account, only once userspace clears the property (sets it back
+to 0).
+
+The size of this internal buffer, and hence the maximum frame size (width x
+height x bytes-per-pixel) that can be held for self-refresh, varies per SoC family:
+
++----------------------------------+-----------------------------------+
+| SoC Family                       | Self-Refresh Internal Buffer Size |
++==================================+===================================+
+| AM65X                            | 40 KB                             |
++----------------------------------+-----------------------------------+
+| AM62X                            | 40 KB                             |
++----------------------------------+-----------------------------------+
+| AM62AX                           | 40 KB                             |
++----------------------------------+-----------------------------------+
+| AM62PX / J722S                   | 40 KB                             |
++----------------------------------+-----------------------------------+
+| AM62LX                           | 20 KB                             |
++----------------------------------+-----------------------------------+
+| J721E / J721S2 / J784S4 / J742S2 | 64 KB                             |
++----------------------------------+-----------------------------------+
+
+If the frame to be looped is larger than the internal buffer size for the given SoC,
+``SELF_REFRESH`` will not activate for that plane.
+
+.. code-block:: console
+
+   $ modetest -M tidss -w 35:SELF_REFRESH:1
+
+In this example, ``SELF_REFRESH`` is enabled on plane 35. The plane keeps displaying
+whatever frame was on screen at the time the property was set; any subsequent frame
+that an application pushes to the plane is dropped by the driver while the property
+remains set. See the combined example under **Always On Display** below for how
+this is used together with ``kmstest``.
+
+.. rubric:: Always On Display
+
+Keep the display pipeline powered after the application exits (and, with additional
+firmware-side support, across system suspend/resume — see the note below).
+
+The ``ALWAYS_ON_DISPLAY`` crtc property is a boolean property. When set to 1, the
+driver keeps the video port's power domain, along with the power domains of any
+bridges and PHYs (for example DSI and D-PHY) in that video port's pipeline, powered
+on even after the last DRM client using the crtc exits, and across system suspend
+and resume. This avoids incurring the cost of hardware reinitialisation of the
+DSI/D-PHY link the next time an application opens the device, at the cost of
+keeping that hardware powered while idle.
+
+This is implemented with two complementary PM holds applied to tidss and to every
+bridge/PHY device in the pipeline:
+
+- A ``pm_runtime_get_noresume()`` hold on each device, which prevents its runtime
+  PM ``suspend`` callback from running (and hence gates runtime autosuspend for
+  tidss itself, not only the external bridges/PHYs).
+- ``dev_pm_genpd_set_always_on()``, which marks the device's power domain as
+  always-on, blocking both runtime power-off and the power-off that would
+  otherwise happen when the system is suspended.
+
+Both holds are released once ``ALWAYS_ON_DISPLAY`` is cleared on all crtcs that had
+it set.
+
+.. ifconfig:: CONFIG_part_variant in ('AM62LX')
+
+   .. note::
+
+      Keeping the display pipeline powered across the Linux driver's own suspend/resume
+      calls is handled entirely by the ``ALWAYS_ON_DISPLAY`` property as described above.
+      However, surviving an actual system-wide low power state (for example
+      ``echo mem > /sys/power/state``) additionally requires cooperation from the
+      device firmware, which must also be told to keep the display power rails on
+      during that low power state. This firmware-side support is available on
+      AM62LX as the :ref:`dss-plus-deepsleep` low power mode.
+
+.. ifconfig:: CONFIG_part_variant not in ('AM62LX')
+
+   .. note::
+
+      Keeping the display pipeline powered across the Linux driver's own suspend/resume
+      calls is handled entirely by the ``ALWAYS_ON_DISPLAY`` property as described above.
+      However, surviving an actual system-wide low power state (for example
+      ``echo mem > /sys/power/state``) additionally requires cooperation from the
+      device firmware, which must also be told to keep the display power rails on
+      during that low power state. This firmware-side support is currently only
+      available on AM62LX. For other SoCs,``ALWAYS_ON_DISPLAY`` keeps the pipeline
+      powered across application handoff, thus avoiding runtime suspend even if no
+      application is holding a reference, but the display should be assumed to
+      lose power during a full system suspend/resume cycle.
+
+.. code-block:: console
+
+   $ modetest -M tidss -w 42:ALWAYS_ON_DISPLAY:1
+
+In this example, crtc 42 has ``ALWAYS_ON_DISPLAY`` set to 1. Once the application
+using this crtc exits, the video port and its associated bridge/PHY power domains
+remain powered on, so a subsequent application can reuse the pipeline without
+incurring the cost of hardware reinitialisation of the DSI/D-PHY link.
+
+When ``ALWAYS_ON_DISPLAY`` is combined with ``SELF_REFRESH`` on a plane of the same
+crtc, the video port itself is also kept running (instead of being disabled) once
+the application exits, so the frame looped by ``SELF_REFRESH`` continues to be
+displayed even after application handoff or system suspend/resume.
+
+.. code-block:: console
+
+   $ modetest -M tidss -w 42:ALWAYS_ON_DISPLAY:1
+   $ modetest -M tidss -w 35:SELF_REFRESH:1
+   $ kmstest --flip
+
+In this combined example, crtc 42 is first set to ``ALWAYS_ON_DISPLAY`` and plane 35
+(belonging to that crtc) is set to ``SELF_REFRESH``. ``kmstest --flip`` is then run to
+exercise page-flipping on the display. While ``SELF_REFRESH`` remains set, the new
+frames that ``kmstest`` flips in are dropped by the driver and the plane keeps
+looping the frame it was set to. When ``kmstest`` exits, the video port is not
+torn down (because both properties are set together), so the same frame keeps
+looping on screen even after the application exits.
+
 Buffers
 -------