feat(DSS7): Document SELF_REFRESH and ALWAYS_ON_DISPLAY properties

Add the SELF_REFRESH (plane) and ALWAYS_ON_DISPLAY (crtc) DRM
properties to the tidss properties table, along with usage
sections describing their behaviour and modetest examples,
following the format used for the other documented properties.

Signed-off-by: Devarsh Thakkar <devarsht@ti.com>

Author: Devarsh Thakkar

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

@@ -508,6 +508,12 @@ tidss supports configuration via DRM properties. These are standard DRM properti
 +--------------------+----------+------------------------------------------------------------------------------------------------------+
 | 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;   |
+|                    |          | the driver ignores new framebuffers submitted by userspace until userspace clears the property.      |
++--------------------+----------+------------------------------------------------------------------------------------------------------+
+| 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,131 @@ For further information on gamma correction:
 *  `<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 the last displayed frame in a loop by using the DSS internal buffer.
+
+The ``SELF_REFRESH`` plane property is a boolean property. When userspace sets it
+to 1, the DSS hardware loops the last frame the plane received from its internal
+buffer. The driver silently ignores any new framebuffer that userspace submits
+while the property remains set. The display resumes normal operation, taking new
+framebuffers into account, only after userspace clears the property (sets it back
+to 0).
+
+The size of this internal buffer varies per SoC family, and therefore so does the
+maximum frame size (width x height x bytes-per-pixel) that self-refresh can loop:
+
++----------------------------------+-----------------------------------+
+| 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 exceeds 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 when userspace set the property. The driver drops any
+later frame that an application pushes to the plane while the property remains set.
+The combined example under **Always On Display** below shows how ``kmstest``
+exercises ``SELF_REFRESH`` together with ``ALWAYS_ON_DISPLAY``.
+
+.. rubric:: Always On Display
+
+Keep the display pipeline powered after the application exits. With additional
+firmware-side support, the pipeline also stays powered across system suspend and
+resume; see the note that follows.
+
+The ``ALWAYS_ON_DISPLAY`` crtc property is a boolean property. When set to 1, the
+driver keeps the video port's power domain powered, along with the power domains
+of its bridges and PHYs (for example DSI and D-PHY). This holds for that video
+port's entire pipeline 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 therefore 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
 -------