diff options
author | Daniel Vetter <daniel.vetter@ffwll.ch> | 2015-09-08 13:52:45 +0200 |
---|---|---|
committer | Daniel Vetter <daniel.vetter@ffwll.ch> | 2015-09-08 15:22:25 +0200 |
commit | 6e48ae3269e3b89d8014d0eb2e35678b0d242b3d (patch) | |
tree | 8f2553acfcebb434cc554c2a4b64914709b2ecb7 /drivers/gpu/drm/drm_atomic_helper.c | |
parent | aef9dbb8f779ae0ffb46313b07700cac72b58ff4 (diff) | |
download | op-kernel-dev-6e48ae3269e3b89d8014d0eb2e35678b0d242b3d.zip op-kernel-dev-6e48ae3269e3b89d8014d0eb2e35678b0d242b3d.tar.gz |
drm/atomic-helper: Pimp docs with recommendations for rpm drivers
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.
v3: Big reword for commit_planes() kerneldoc based on a text from
Laurent.
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Thierry Reding <treding@nvidia.com> (v1 on irc)
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Diffstat (limited to 'drivers/gpu/drm/drm_atomic_helper.c')
-rw-r--r-- | drivers/gpu/drm/drm_atomic_helper.c | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c index 12c25c5..77d55a9 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,22 @@ 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. + * + * 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. This avoids the need to manually ignore plane updates in + * driver code when the driver and/or hardware can't or just don't need to deal + * with updates on disabled CRTCs, for example when supporting runtime PM. + * + * The drm_atomic_helper_commit() default implementation only sets @active_only + * to false to most closely match the behaviour of the legacy helpers. This should + * not be copied blindly by drivers. */ void drm_atomic_helper_commit_planes(struct drm_device *dev, struct drm_atomic_state *old_state, |