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

[Laurent Pinchart]

Hi Daniel,

Thank you for the patch.

On Tuesday 08 September 2015 13:52:45 Daniel Vetter wrote:
> 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.

How about

"Plane parameters can be updated by applications while the associated CRTC is 
disabled. The DRM/KMS core will store the parameters in the plane state, which 
will be available to the driver when the CRTC is turned on. As a result most 
drivers don't need to be immediately notified of plane updates for a disabled 
CRTC. Unless otherwise needed, drivers are advised to set the @active_only 
parameters to true in order not to receive plane update notifications related 
to a disabled CRTC."

>   */
>  void drm_atomic_helper_commit_planes(struct drm_device *dev,
>  				     struct drm_atomic_state *old_state,

-- 
Regards,

Laurent Pinchart