feat[DSS7]: Document SELF_REFRESH and ALWAYS_ON_DISPLAY properties by devarsht · Pull Request #760 · TexasInstruments/processor-sdk-doc

devarsht · 2026-07-28T14:31:58Z

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.

StaticRocket

There's also some unnecessary use of passive voice in here

SenWang125 · 2026-07-29T02:53:32Z

Don't have any comments, looks good to me.

devarsht · 2026-07-29T18:23:32Z

There's also some unnecessary use of passive voice in here

@StaticRocket Yeah but re-reading those sentences which vale reported, those sentences look very much understandable/readable to me and I would prefer to keep that way. But if it's a more popular opinion to always use active voice I can always modify.

StaticRocket · 2026-07-29T20:57:47Z

Technical documentation is normally declarative and uses active voice. As an example of what I mean: We are dictating the way something behaves under optimal conditions. We are not writing to a friend about something that may or may not happen due to circumstance.

It makes it dry, but brief, easier to translate, and usually easier to understand.

StaticRocket · 2026-07-29T20:58:48Z

You're also bugging commit-check with that patch formatting

devarsht · 2026-07-30T10:44:50Z

Technical documentation is normally declarative and uses active voice. As an example of what I mean: We are dictating the way something behaves under optimal conditions. We are not writing to a friend about something that may or may not happen due to circumstance.

It makes it dry, but brief, easier to translate, and usually easier to understand.

Hmm, but when describing properties, passive voice is what is mostly what is preferred. See below examples from kernel docs and gstreamer docs:

Kernel docs :
See for e.g. : https://www.kernel.org/doc/html/v4.14/media/uapi/v4l/extended-controls.html?highlight=ignored

For e.g. kernel doc uses passive voice:
V4L2_CID_MPEG_VIDEO_BITRATE_PEAK (integer)
Peak video bitrate in bits per second. Must be larger or equal to the average video bitrate. It is ignored if the video bitrate mode is set to constant bitrate.

And here too:
V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE (integer)
The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip

Gstreamer docs:
https://gstreamer.freedesktop.org/documentation/video4linux2/v4l2src.html?gi-language=c

force-aspect-ratio
“force-aspect-ratio” gboolean
When enabled, the pixel aspect ratio queried from the device or set with the pixel-aspect-ratio property will be enforced.

Flags : Read / Write

Default value : true

StaticRocket · 2026-07-30T19:52:43Z

All of those examples could easily use active voice to convey the same thing in fewer words:

Peak video bitrate in bits per second. Must be larger or equal to the average video bitrate. It is ignored if the video bitrate mode is set to constant bitrate.

Peak video bitrate in bits per second. Must be larger or equal to the average video bitrate. When using a constant bitrate this value does nothing.

The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip

The Coded Picture Buffer size in kilobytes. This can be a limitation of frame skip.

That sentence is a little weird as written though. Think you may have left some part of it off. The way it was written is a little vague. it is used as a limitation of frame skip indicates that, though that may not be what it's actually for, it's commonly used for that purpose. Maybe I'm just interpreting that incorrectly. If so then the rewrite above could be much more brief.

Any project is free to do what it wants, I'm just trying to enforce standard practices here.

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>

devarsht · 2026-07-31T12:25:51Z

All of those examples could easily use active voice to convey the same thing in fewer words:

Peak video bitrate in bits per second. Must be larger or equal to the average video bitrate. It is ignored if the video bitrate mode is set to constant bitrate.

Peak video bitrate in bits per second. Must be larger or equal to the average video bitrate. When using a constant bitrate this value does nothing.

The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip

The Coded Picture Buffer size in kilobytes. This can be a limitation of frame skip.

That sentence is a little weird as written though. Think you may have left some part of it off. The way it was written is a little vague. it is used as a limitation of frame skip indicates that, though that may not be what it's actually for, it's commonly used for that purpose. Maybe I'm just interpreting that incorrectly. If so then the rewrite above could be much more brief.

Any project is free to do what it wants, I'm just trying to enforce standard practices here.

Alright, thanks for sharing, Updated the PR as suggested.

devarsht · 2026-07-31T12:26:23Z

You're also bugging commit-check with that patch formatting

Yes, fixed that too.

jainswamil

Looks good

akashdeep-ti · 2026-08-03T12:27:56Z

+----------------------------------+-----------------------------------+
+
+If the frame exceeds the internal buffer size for the given SoC, ``SELF_REFRESH``
+will not activate for that plane.


So, Self refresh property will still be set to 1 but nothing will be visible on display or neither property will be set to 1 nor will anything be displayed?
Can you please add this clearly so that the user can know how to recover from such scenarios (activate is a bit confusing to understand)

akashdeep-ti · 2026-08-03T12:35:31Z

+reinitialization of the DSI and D-PHY link the next time an application opens the
+device, at the cost of keeping that hardware powered while idle.
+
+The driver applies two complementary PM holds to tidss and to every bridge/PHY


PM holds is a confusing term, can we make it simpler

akashdeep-ti · 2026-08-03T13:01:38Z

+      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


is currently gives an impression that it is possible to add support for this to other devices in future, which is not correct.
Can we reword it to state that this is only possible on AM62L SoC.

StaticRocket · 2026-08-04T03:00:55Z

 .. ifconfig:: CONFIG_part_variant in ('J721E', 'J721S2', 'J784S4','J742S2')

    .. Image:: /images/DSS7_HW.png

 .. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM65X', 'AM62AX', 'AM62PX', 'J722S')

    .. Image:: /images/DSS7Lite_HW.png


-The above image gives an overview of the DSS hardware.
+.. ifconfig:: CONFIG_part_variant in ('J721E', 'J721S2', 'J784S4', 'J742S2', 'AM62X', 'AM65X', 'AM62AX', 'AM62PX', 'J722S')
+
+    The above image gives an overview of the DSS hardware.


Suggested change

The above image gives an overview of the DSS hardware.

.. ifconfig:: CONFIG_part_variant in ('J721E', 'J721S2', 'J784S4','J742S2')

.. figure:: /images/DSS7_HW.png

Overview of DSS Hardware

.. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM65X', 'AM62AX', 'AM62PX', 'J722S')

.. figure:: /images/DSS7Lite_HW.png

Overview of DSS Hardware

StaticRocket · 2026-08-04T03:10:57Z

+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


Please update the vale accept.txt for the plural form of framebuffer.

[Ff]ramebuffers?

StaticRocket · 2026-08-04T03:12:22Z

+| 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,        |


CRTC is an acronym. Why is it lowercase in this file?

StaticRocket · 2026-08-04T03:13:35Z

+Abbreviations
+=============
+
+-----------------+--------------------------------------------------------------+
+| Abbreviation    | Description                                                  |
+=================+==============================================================+


Suggested change

Abbreviations

=============

+-----------------+--------------------------------------------------------------+

| Abbreviation | Description |

+=================+==============================================================+

Acronyms

========

+-----------------+--------------------------------------------------------------+

| Acronym | Description |

+=================+==============================================================+

I appreciate this effort, but it doesn't really make vale happy. Still looking at adding a global glossary for all of this. Unfortunately even with a global glossary I think we'll have domain specific overlaps. Still not entirely sure how I want that to work.

devarsht requested review from StaticRocket, VeeruPrudhvi, cshilwant, gehariprasath, jeevantelukula, praneethbajjuri and uditkumarti as code owners July 28, 2026 14:32

github-actions Bot assigned devarsht, gehariprasath, praneethbajjuri, r-vignesh and uditkumarti Jul 28, 2026

github-actions Bot requested a review from r-vignesh July 28, 2026 14:32

StaticRocket requested changes Jul 28, 2026

View reviewed changes

devarsht force-pushed the dss_aod_sr branch from 14c0c87 to 58baf25 Compare July 29, 2026 18:16

devarsht force-pushed the dss_aod_sr branch 5 times, most recently from a4434a1 to ff79076 Compare July 31, 2026 10:42

devarsht force-pushed the dss_aod_sr branch from ff79076 to e4bdbff Compare July 31, 2026 12:20

devarsht closed this Jul 31, 2026

devarsht reopened this Jul 31, 2026

devarsht requested a review from StaticRocket August 3, 2026 06:19

jainswamil approved these changes Aug 3, 2026

View reviewed changes

akashdeep-ti suggested changes Aug 3, 2026

View reviewed changes

StaticRocket requested changes Aug 4, 2026

View reviewed changes

-    The above image gives an overview of the DSS hardware.
+.. ifconfig:: CONFIG_part_variant in ('J721E', 'J721S2', 'J784S4','J742S2')
+   .. figure:: /images/DSS7_HW.png
+      Overview of DSS Hardware
+.. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM65X', 'AM62AX', 'AM62PX', 'J722S')
+   .. figure:: /images/DSS7Lite_HW.png
+      Overview of DSS Hardware

Uh oh!

Conversation

devarsht commented Jul 28, 2026

Uh oh!

StaticRocket left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

SenWang125 commented Jul 29, 2026

Uh oh!

devarsht commented Jul 29, 2026

Uh oh!

StaticRocket commented Jul 29, 2026

Uh oh!

StaticRocket commented Jul 29, 2026

Uh oh!

devarsht commented Jul 30, 2026

Uh oh!

StaticRocket commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devarsht commented Jul 31, 2026

Uh oh!

devarsht commented Jul 31, 2026

Uh oh!

jainswamil left a comment

Choose a reason for hiding this comment

Uh oh!

akashdeep-ti Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

akashdeep-ti Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

akashdeep-ti Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

StaticRocket Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

StaticRocket Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

StaticRocket Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

StaticRocket Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

9 participants

StaticRocket commented Jul 30, 2026 •

edited

Loading