[Intel-gfx] [PATCH 4/4] drm/i915: Add PSR docbook

[Rodrigo Vivi]

Let's document PSR a bit. No functional changes.

Signed-off-by: Rodrigo Vivi <rodrigo.vivi at intel.com>
---
 drivers/gpu/drm/i915/intel_psr.c | 58 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/drivers/gpu/drm/i915/intel_psr.c b/drivers/gpu/drm/i915/intel_psr.c
index 793f491..5f350f0 100644
--- a/drivers/gpu/drm/i915/intel_psr.c
+++ b/drivers/gpu/drm/i915/intel_psr.c
@@ -21,6 +21,26 @@
  * DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * DOC: Panel Self Refresh (PSR/SRD)
+ *
+ * Since 4th Generation Intel® Core™ processors with Intel® HD Graphics
+ * (Haswell) Display controller supports Panel Self-Refresh on display panels
+ * witch have a remote frame buffer (RFB) implemented according to PSR spec in
+ * eDP1.3. PSR feature allows the display to go to lower standby states when
+ * system is idle but display is on as it eliminates diplay refresh request
+ * to DDR memory completely as long as the frame buffer for that display is
+ * unchanged.
+ *
+ * Panel Self Refresh must be supported by both Hardware (source) and
+ * Panel (sink).
+ *
+ * The PSR feature enables system-level power savings when the displayed image
+ * remains static for multiple display frames. The Sink device stores a static
+ * image locally in the RFB within the Sink device, and displays this image
+ * from the RFB, while the eDP Main-Link can be turned OFF.
+ */
+
 #include <drm/drmP.h>
 
 #include "intel_drv.h"
@@ -222,6 +242,13 @@ static void intel_psr_do_enable(struct intel_dp *intel_dp)
 	dev_priv->psr.active = true;
 }
 
+/**
+ * intel_psr_enable - Enable PSR
+ * @intel_dp: Intel DP
+ *
+ * This function gets called every time eDP panel is turned on. Right after
+ * turning backlight on.
+ */
 void intel_psr_enable(struct intel_dp *intel_dp)
 {
 	struct intel_digital_port *intel_dig_port = dp_to_dig_port(intel_dp);
@@ -263,6 +290,13 @@ unlock:
 	mutex_unlock(&dev_priv->psr.lock);
 }
 
+/**
+ * intel_psr_disable - Disable PSR
+ * @intel_dp: Intel DP
+ *
+ * This function gets called every time eDP panel is turned off. Right before
+ * turning backlight off.
+ */
 void intel_psr_disable(struct intel_dp *intel_dp)
 {
 	struct intel_digital_port *intel_dig_port = dp_to_dig_port(intel_dp);
@@ -347,6 +381,16 @@ static void intel_psr_exit(struct drm_device *dev)
 
 }
 
+/**
+ * intel_psr_invalidate - Invalidade PSR
+ * @dev: DRM device
+ * @frontbuffer_bits: frontbuffer plane tracking bits
+ *
+ * Hardware (source) is usually the responsible for identifying when the screen
+ * changed and Remote Frame Buffer must be updated. However this HW tracking
+ * doesn't cover all cases. So we can take advantage of frontbuffer tracking
+ * to force a psr_exit when driver knows RFB must be updated.
+ */
 void intel_psr_invalidate(struct drm_device *dev,
 			      unsigned frontbuffer_bits)
 {
@@ -371,6 +415,14 @@ void intel_psr_invalidate(struct drm_device *dev,
 	mutex_unlock(&dev_priv->psr.lock);
 }
 
+/**
+ * intel_psr_flush - Flush PSR
+ * @dev: DRM device
+ * @frontbuffer_bits: frontbuffer plane tracking bits
+ *
+ * After PSR got invalidated forcing PSR exit and RFB update driver must also
+ * take care to flush it allowing PSR to come back to regular work.
+ */
 void intel_psr_flush(struct drm_device *dev,
 			 unsigned frontbuffer_bits)
 {
@@ -404,6 +456,12 @@ void intel_psr_flush(struct drm_device *dev,
 	mutex_unlock(&dev_priv->psr.lock);
 }
 
+/**
+ * intel_psr_init - Init basic PSR work and mutex.
+ * @dev: DRM device
+ *
+ * This function is to be called only once to initialize basic PSR stuff.
+ */
 void intel_psr_init(struct drm_device *dev)
 {
 	struct drm_i915_private *dev_priv = dev->dev_private;
-- 
1.9.3