[PATCH] drm/atomic-helper: Pimp docs with recommendations for rpm drivers

[Daniel Vetter]

Requested by Laurent.

Note that this uses the new markdown support which will only land in
kernel 4.4 (for the code snippet).

v2: A few spelling fixes I spotted myself.

Cc: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
Reviewed-by: Thierry Reding <treding at nvidia.com> (v1 on irc)
Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
---
 drivers/gpu/drm/drm_atomic_helper.c | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c
index 12c25c54309f..bd23b4dc7f43 100644
--- a/drivers/gpu/drm/drm_atomic_helper.c
+++ b/drivers/gpu/drm/drm_atomic_helper.c
@@ -993,6 +993,22 @@ EXPORT_SYMBOL(drm_atomic_helper_wait_for_vblanks);
  * object. This can still fail when e.g. the framebuffer reservation fails. For
  * now this doesn't implement asynchronous commits.
  *
+ * Note that right now this function does not support async commits, and hence
+ * driver writers must implement their own version for now. Also note that the
+ * default ordering of how the various stages are called is to match the legacy
+ * modeset helper library closest. One peculiarity of that is that it doesn't
+ * mesh well with runtime pm at all.
+ *
+ * For drivers supporting runtime PM the recommended sequence is
+ *
+ *     drm_atomic_helper_commit_modeset_disables(dev, state);
+ *
+ *     drm_atomic_helper_commit_modeset_enables(dev, state);
+ *
+ *     drm_atomic_helper_commit_planes(dev, state, true);
+ *
+ * See the kerneldoc entries for these three functions for more details.
+ *
  * RETURNS
  * Zero for success or -errno.
  */
@@ -1168,6 +1184,12 @@ bool plane_crtc_active(struct drm_plane_state *state)
  * Note that this function does all plane updates across all CRTCs in one step.
  * If the hardware can't support this approach look at
  * drm_atomic_helper_commit_planes_on_crtc() instead.
+ *
+ * Note that for drivers supporting runtime PM, or which are otherwise unhappy if
+ * their plane update hooks get called on CRTCs which are off, it is highly
+ * recommended to set @active_only to true. Setting @active_only to false as the
+ * default implementation in drm_atomic_helper_commit() does is just done to
+ * most closely match the behaviour of the legacy helpers.
  */
 void drm_atomic_helper_commit_planes(struct drm_device *dev,
 				     struct drm_atomic_state *old_state,
-- 
2.5.1