diff --git a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7.rst b/source/linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7.rst index 072e05f86..23235e5b7 100644 --- a/source/linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7.rst +++ b/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; | +| | | 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 @@ For further information on gamma correction: * ``__ * ``__ +.. 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 -------