From patchwork Wed Mar 1 08:35:34 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Daniel Vetter X-Patchwork-Id: 9597799 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id C2E3B60429 for ; Wed, 1 Mar 2017 08:35:50 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id AB7BD26E4E for ; Wed, 1 Mar 2017 08:35:50 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 9E991284E7; Wed, 1 Mar 2017 08:35:50 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.1 required=2.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_MED,T_DKIM_INVALID autolearn=ham version=3.3.1 Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id ED9B826E4E for ; Wed, 1 Mar 2017 08:35:49 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 031F06E8CC; Wed, 1 Mar 2017 08:35:48 +0000 (UTC) X-Original-To: dri-devel@lists.freedesktop.org Delivered-To: dri-devel@lists.freedesktop.org Received: from mail-wm0-x242.google.com (mail-wm0-x242.google.com [IPv6:2a00:1450:400c:c09::242]) by gabe.freedesktop.org (Postfix) with ESMTPS id 813526E8CC for ; Wed, 1 Mar 2017 08:35:46 +0000 (UTC) Received: by mail-wm0-x242.google.com with SMTP id u63so6024422wmu.2 for ; Wed, 01 Mar 2017 00:35:46 -0800 (PST) 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=iq01eptXn4COJ82tDmFH3wX2I7UUaSh2VUVP/vgUgaY=; b=crr1bAWzOFB13pighvBBkJpo411s0xyGLP9VURax09ywqGmrs+M4SnlVYhLiucE3uR r8oaiRMqDE1Bvmxl4KHyCsUOCxH7hEC3vqUeh+il29zHRjK9P69QYQWo1WibUK+JwnBW mLY9fIbyQEda02EUBxe5+q/n7w3fpFjZ3q+zc= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=iq01eptXn4COJ82tDmFH3wX2I7UUaSh2VUVP/vgUgaY=; b=SbtwgKyiQox7ES9Xuz7e3XCI5XpE7LOQ12dUXrTFbZHVV9Yd92A7I9GqS+l85IhuSo ChSRgTPY44Kubsnt8OynIbkHJS9ZBc1kfD0tcxvsaq7K+CW9FjSMmhCnOEiV8Ndy4uDN iT/cQzu4qL3/krcFuM5s0MMSnZDq+BoMV5DNjxwnKkpnDBsbQl5DeLSJwG8cklUMfJ3U OPbBlWhI3vvCZ0Zce/jjuv4BLVIaiDMSr8kqWYx6DrLV6O/Rp7hH5b0KyUkGzGxF5HJC szwILdz6hV375kKsXFhBJorVcHmZ/3kHIRt6STlJFLiZRq5YXbNA4vCfK4UbgFwoKDvH 1zEA== X-Gm-Message-State: AMke39kccHFCjOJwsUfv08Vqm4mdh77DXnf3exqJPHAtBVmOA67/mm/C2Gmqi/xgwmzvbQ== X-Received: by 10.28.86.214 with SMTP id k205mr2041981wmb.26.1488357344994; Wed, 01 Mar 2017 00:35:44 -0800 (PST) Received: from phenom.ffwll.local ([2a02:168:56c9:0:decc:6e78:7e96:b452]) by smtp.gmail.com with ESMTPSA id q1sm5945360wmd.6.2017.03.01.00.35.43 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 01 Mar 2017 00:35:44 -0800 (PST) From: Daniel Vetter To: linux-doc@vger.kernel.org Subject: [PATCH] drm/doc: atomic overview, with graph Date: Wed, 1 Mar 2017 09:35:34 +0100 Message-Id: <20170301083534.1522-1-daniel.vetter@ffwll.ch> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20170228171319.1786-7-daniel.vetter@ffwll.ch> References: <20170228171319.1786-7-daniel.vetter@ffwll.ch> Cc: Daniel Vetter , DRI Development , Laurent Pinchart , Daniel Vetter X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" X-Virus-Scanned: ClamAV using ClamSMTP I want to split up a few more things and document some details better (like how exactly to subclass drm_atomic_state). And maybe also split up the helpers a bit per-topic, but this should be a ok-ish start for better atomic overview. One thing I failed at is getting DOT to layout the overview graph how I want it. The highlevel structure I want is: Free-standing State Current State i.e. one over the other. Currently it lays it out side-by-side, but not even that really - "Current State" is somewhat offset below. Makes the graph look like garbage, and also way too wide for proper rendering. Ideas appreciated. v2: Spelling and clarifications (Eric). Cc: Eric Anholt Cc: Laurent Pinchart Cc: Harry Wentland Signed-off-by: Daniel Vetter Acked-by: Eric Anholt --- Documentation/gpu/drm-kms-helpers.rst | 2 + Documentation/gpu/drm-kms.rst | 86 ++++++++++++++++++++++++++++++++++- 2 files changed, 87 insertions(+), 1 deletion(-) diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 050ebe81d256..ac53c0b893f6 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -42,6 +42,8 @@ Modeset Helper Reference for Common Vtables .. kernel-doc:: include/drm/drm_modeset_helper_vtables.h :internal: +.. _drm_atomic_helper: + Atomic Modeset Helper Functions Reference ========================================= diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index a504d9ee4d94..4823df03c773 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -189,8 +189,92 @@ multiple times to different objects using :c:func:`drm_object_attach_property() .. kernel-doc:: drivers/gpu/drm/drm_mode_object.c :export: +Atomic Mode Setting +=================== + + +.. FIXME: The I want the below graph to be laid out so that the 2 subgraph + clusters are below each another. But I failed. + +.. kernel-render:: DOT + :alt: Mode Objects and Properties + :caption: Mode Objects and Properties + + digraph { + node [shape=box] + + subgraph cluster_state { + style=dashed + label="Free-standing state" + + "drm_atomic_state" -> "duplicated drm_plane_state A" + "drm_atomic_state" -> "duplicated drm_plane_state B" + "drm_atomic_state" -> "duplicated drm_crtc_state" + "drm_atomic_state" -> "duplicated drm_connector_state" + "drm_atomic_state" -> "duplicated driver private state" + } + + subgraph cluster_current { + style=dashed + label="Current state" + + "drm_device" -> "drm_plane A" + "drm_device" -> "drm_plane B" + "drm_device" -> "drm_crtc" + "drm_device" -> "drm_connector" + "drm_device" -> "driver private object" + + "drm_plane A" -> "drm_plane_state A" + "drm_plane B" -> "drm_plane_state B" + "drm_crtc" -> "drm_crtc_state" + "drm_connector" -> "drm_connector_state" + "driver private object" -> "driver private state" + } + + "drm_atomic_state" -> "drm_device" [label="atomic_commit"] + } + +Atomic provides transactional modeset (including planes) updates, but a +bit differently from the usual transactional approach of try-commit and +rollback: + +- Firstly, no hardware changes are allowed when the commit would fail. This + allows us to implement the DRM_MODE_ATOMIC_TEST_ONLY mode, which allows + userspace to explore whether certain configurations would work or not. + +- This would still allow setting and rollback of just the software state, + simplifying conversion of existing drivers. But auditing drivers for + correctness of the atomic_check code becomes really hard with that: Rolling + back changes in data structures all over the place is hard to get right. + +- Lastly, for backwards compatibility and to support all use-cases, atomic + updates need to be incremental and be able to execute in parallel. Hardware + doesn't always allow it, but where possible plane updates on different CRTCs + should not interfere, and not get stalled due to output routing changing on + different CRTCs. + +Taken all together there's two consequences for the atomic design: + +- The overall state is split up into per-object state structures: + :c:type:`struct drm_plane_state ` for planes, :c:type:`struct + drm_crtc_state ` for CRTCs and :c:type:`struct + drm_connector_state ` + container. Again drivers can subclass that container for their own state + structure tracking needs. Only when a state is committed is it applied to the + driver and modeset objects. This way rolling back an update boils down to + releasing memory and unreferencing objects like framebuffers. + +Read on in this chapter, and also in :ref:`drm_atomic_helper` for more detailed +coverage of specific topics. + Atomic Mode Setting Function Reference -====================================== +-------------------------------------- .. kernel-doc:: include/drm/drm_atomic.h :internal: