From patchwork Tue Sep 8 13:22:54 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 7141021 Return-Path: X-Original-To: patchwork-intel-gfx@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id EDCCF9F665 for ; Tue, 8 Sep 2015 13:20:19 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id EC3D420647 for ; Tue, 8 Sep 2015 13:20:18 +0000 (UTC) Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) by mail.kernel.org (Postfix) with ESMTP id EDFCE2063F for ; Tue, 8 Sep 2015 13:20:17 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id B7D4E6E918; Tue, 8 Sep 2015 06:20:16 -0700 (PDT) X-Original-To: intel-gfx@lists.freedesktop.org Delivered-To: intel-gfx@lists.freedesktop.org Received: from mail-wi0-f181.google.com (mail-wi0-f181.google.com [209.85.212.181]) by gabe.freedesktop.org (Postfix) with ESMTPS id 624736E90A for ; Tue, 8 Sep 2015 06:20:15 -0700 (PDT) Received: by wicge5 with SMTP id ge5so116506692wic.0 for ; Tue, 08 Sep 2015 06:20:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ffwll.ch; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=uSgwiGuyCRFWykX0mgWvnFWwSwnJte/goh+U5lVYSh0=; b=Rj1bBLsvIQvYHC37FZ3WSQrPEijv3EdEjQIsI2h7jPTD3OzCUkvfxhhJXvXEN4uwYP B2FpD2EwNHfttKPx4LbcQJS+CJzQizIcoadmBjCBJmNdmTzAv0NICiYTvX2P8GK/dVG5 0YyIn2KEKmzIl2Qt4yDUt1ngIBXNvc27+qkpI= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=uSgwiGuyCRFWykX0mgWvnFWwSwnJte/goh+U5lVYSh0=; b=cD2o7z5Q3z1DnbyXxM9PJDEtsAzxsuDguKj4kao+e9/MkXnUDMpttTCVaXnL3UXVyt YxCZKLALF6AqWLFXCnTy+c+NEwtDx+j/wb8bIPzNycUeG+oMEVgrz5vQUTWIkWUCc1EB WTSPv66p3UcnFvbxY6YA/BI6ve9pmwwoU2P5oaFfb+pRpPb33+Sr++YoapSayfw7UJGz kDNRnDsvJHnJ2EG02tvPfKuL3ExZNFkkOEt0y4NvpzdexZjydeqFLiGBF9gy9jCGYYbx nBkYXu8ulvbQ3KNWCoggS/v7l35Qh0y3gNpTqbIOJd+UbTCp3IknLlm6D6bfszXjm4Z6 alZA== X-Gm-Message-State: ALoCoQkfyhzH4KyqK4lxx74eWZXzproSW3l8uOEe3IVjTNBN7z+DukkyVtjnw6Pgf44Z2I+pWtEx X-Received: by 10.180.20.177 with SMTP id o17mr43737539wie.93.1441718413878; Tue, 08 Sep 2015 06:20:13 -0700 (PDT) Received: from phenom.ffwll.local (212-51-149-109.fiber7.init7.net. [212.51.149.109]) by smtp.gmail.com with ESMTPSA id v6sm4858763wjf.13.2015.09.08.06.20.12 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Tue, 08 Sep 2015 06:20:13 -0700 (PDT) From: Daniel Vetter To: DRI Development Date: Tue, 8 Sep 2015 15:22:54 +0200 Message-Id: <1441718574-10804-1-git-send-email-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.5.1 In-Reply-To: <1441713165-24465-1-git-send-email-daniel.vetter@ffwll.ch> References: <1441713165-24465-1-git-send-email-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , Intel Graphics Development , Laurent Pinchart , Daniel Vetter Subject: [Intel-gfx] [PATCH] drm/atomic-helper: Pimp docs with recommendations for rpm drivers X-BeenThere: intel-gfx@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Intel graphics driver community testing & development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" X-Spam-Status: No, score=-4.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED, T_DKIM_INVALID, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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 Reviewed-by: Thierry Reding (v1 on irc) Acked-by: Laurent Pinchart Signed-off-by: Daniel Vetter --- drivers/gpu/drm/drm_atomic_helper.c | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/drivers/gpu/drm/drm_atomic_helper.c b/drivers/gpu/drm/drm_atomic_helper.c index 12c25c54309f..77d55a935793 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,