feat[DSS7]: Document SELF_REFRESH and ALWAYS_ON_DISPLAY properties

[devarsht]

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]

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

[devarsht]

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]

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]

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

[devarsht]

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]

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.

[devarsht]

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]

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

Yes, fixed that too.

[jainswamil]

Looks good

[StaticRocket]

Slight rephrasing suggested. Also, apparently I didn't notice the previous userspace usage. Trying to standardize on either the traditional user space or kernel user-space notation.

[akashdeep-ti]

Just one minor comment (ignore if it is not valid). Otherwise, LGTM

[devarsht]

Slight rephrasing suggested. Also, apparently I didn't notice the previous userspace usage. Trying to standardize on either the traditional user space or kernel user-space notation.

I would suggest that be a global change that could be a separate PR in itself across all linux docs:

grep -inlr userspace source/linux
source/linux/Industrial_Protocols/_SORTE.rst
source/linux/Industrial_Protocols/PTP/_PTP.rst
source/linux/Foundational_Components_IPC64x.rst
source/linux/Foundational_Components/Power_Management/pm_suspend_resume.rst
source/linux/Foundational_Components/Power_Management/pm_dfs.rst
source/linux/Foundational_Components/Power_Management/pm_dvfs.rst
source/linux/Foundational_Components/IPC/_RPMsg_char_driver.rst
source/linux/Foundational_Components/PRU-ICSS/Linux_Drivers/PRU_ICSSG_XDP.rst
source/linux/Foundational_Components/Hypervisor/Jailhouse.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/DCAN.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/QSPI.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/CPSW-Proxy-Client.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Network/CPSW.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Storage/MMC-SD.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/UART.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/I2C.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/VPE.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/USB/AM62_DWC3.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/USB/DWC3.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/PCIe/PCIe_End_Point.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/ADC.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/_CSI2RX_common.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/VPFE.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/CAL.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Camera/VIP.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Watchdog.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/UFS.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/SPI.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/PWM.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Audio.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/HYPERFLASH.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/E5010_JPEG_Encoder.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS7.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Display/LCDC.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/Display/DSS.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/MCAN.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/DM-Timer.rst
source/linux/Foundational_Components/Kernel/Kernel_Drivers/PMIC/pmic_tps6594.rst
source/linux/Foundational_Components_OPTEE.rst
source/linux/Foundational_Components_Secure_Boot.rst
source/linux/How_to_Guides/Target/How_to_boot_quickly.rst
source/linux/Foundational_Components_IPCLLD.rst