From patchwork Thu Dec 14 10:09:12 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxime Ripard X-Patchwork-Id: 13492696 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 0171AC4332F for ; Thu, 14 Dec 2023 10:09:28 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 0A4EB10E900; Thu, 14 Dec 2023 10:09:27 +0000 (UTC) Received: from sin.source.kernel.org (sin.source.kernel.org [145.40.73.55]) by gabe.freedesktop.org (Postfix) with ESMTPS id 3353F10E8F9 for ; Thu, 14 Dec 2023 10:09:24 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sin.source.kernel.org (Postfix) with ESMTP id B7E43CE10E4; Thu, 14 Dec 2023 10:09:21 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A3E73C433C8; Thu, 14 Dec 2023 10:09:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1702548561; bh=+11YBo0kmFgr2krbb5UDhkf2knSUBIclo+6BcfnIGvs=; h=From:To:Cc:Subject:Date:From; b=juRBcW/iMj5z+FZai6bfPLjompiA9NKXlf5UGxldoNN/zCgTMD+x8Xi3YcmXLxCDN pA5XhL+K50hHq0u6kpbAiImW3MtwsaanSmUbLRDsMbA7zKXx7LLOsGHds7oPrsrwXQ gWaBEdTrDU6k62WiCseUJPHb/x6Ej38BZLldXQTFxuW+rXvPlbeI9P2dBmPWl843rH PjVPpdSBHWcA071klJf2zqoePQiuboOWjGqyLFUztNya0JJXt7evV9j4EovUNZLUSj FRIaGVKL+kxac+M1+tghLMdaqB14JSmIxFwNmj+0THskmXZEkgvMK8+iTsguSWy9g0 B9OxxYp8+uVOA== From: Maxime Ripard To: Daniel Vetter , David Airlie , Maarten Lankhorst , Thomas Zimmermann , Maxime Ripard Subject: [PATCH v2 1/5] drm/atomic: Move the drm_atomic_state field doc inline Date: Thu, 14 Dec 2023 11:09:12 +0100 Message-ID: <20231214100917.277842-1-mripard@kernel.org> X-Mailer: git-send-email 2.43.0 MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Sui Jingfeng , Pekka Paalanen , dri-devel@lists.freedesktop.org Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Some fields of drm_atomic_state have been documented in-line, but some were documented in the main kerneldoc block before the structure. Since the former is the preferred option in DRM, let's move all the fields to an inline documentation. Acked-by: Sui Jingfeng Signed-off-by: Maxime Ripard --- include/drm/drm_atomic.h | 50 ++++++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 10 deletions(-) diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h index cf8e1220a4ac..2a08030fcd75 100644 --- a/include/drm/drm_atomic.h +++ b/include/drm/drm_atomic.h @@ -347,24 +347,22 @@ struct __drm_private_objs_state { /** * struct drm_atomic_state - the global state object for atomic updates - * @ref: count of all references to this state (will not be freed until zero) - * @dev: parent DRM device - * @async_update: hint for asynchronous plane update - * @planes: pointer to array of structures with per-plane data - * @crtcs: pointer to array of CRTC pointers - * @num_connector: size of the @connectors and @connector_states arrays - * @connectors: pointer to array of structures with per-connector data - * @num_private_objs: size of the @private_objs array - * @private_objs: pointer to array of private object pointers - * @acquire_ctx: acquire context for this atomic modeset state update * * States are added to an atomic update by calling drm_atomic_get_crtc_state(), * drm_atomic_get_plane_state(), drm_atomic_get_connector_state(), or for * private state structures, drm_atomic_get_private_obj_state(). */ struct drm_atomic_state { + /** + * @ref: + * + * Count of all references to this update (will not be freed until zero). + */ struct kref ref; + /** + * @dev: Parent DRM Device. + */ struct drm_device *dev; /** @@ -388,7 +386,12 @@ struct drm_atomic_state { * flag are not allowed. */ bool legacy_cursor_update : 1; + + /** + * @async_update: hint for asynchronous plane update + */ bool async_update : 1; + /** * @duplicated: * @@ -398,13 +401,40 @@ struct drm_atomic_state { * states. */ bool duplicated : 1; + + /** + * @planes: pointer to array of structures with per-plane data + */ struct __drm_planes_state *planes; + + /** + * @crtcs: pointer to array of CRTC pointers + */ struct __drm_crtcs_state *crtcs; + + /** + * @num_connector: size of the @connectors and @connector_states arrays + */ int num_connector; + + /** + * @connectors: pointer to array of structures with per-connector data + */ struct __drm_connnectors_state *connectors; + + /** + * @num_private_objs: size of the @private_objs array + */ int num_private_objs; + + /** + * @private_objs: pointer to array of private object pointers + */ struct __drm_private_objs_state *private_objs; + /** + * @acquire_ctx: acquire context for this atomic modeset state update + */ struct drm_modeset_acquire_ctx *acquire_ctx; /** From patchwork Thu Dec 14 10:09:13 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxime Ripard X-Patchwork-Id: 13492698 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 6E80CC4332F for ; Thu, 14 Dec 2023 10:09:38 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 097B010E911; Thu, 14 Dec 2023 10:09:34 +0000 (UTC) Received: from ams.source.kernel.org (ams.source.kernel.org [IPv6:2604:1380:4601:e00::1]) by gabe.freedesktop.org (Postfix) with ESMTPS id 8CFB110E8F9 for ; Thu, 14 Dec 2023 10:09:26 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by ams.source.kernel.org (Postfix) with ESMTP id 9C4D7B82162; Thu, 14 Dec 2023 10:09:24 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A27BCC433C7; Thu, 14 Dec 2023 10:09:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1702548564; bh=w1/ZociL3T5z/9/6oO486hoe6cFIwDEgcc0EjhXmKLk=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=pa2wfRPT3GKRPpyOLUuYO3gC7CPUWMu7xvCoTIANhnV0J8gTycBvPzA7qQzOuJG29 oAqIsgT6KvwxSQswSVkqYHxyD8y/0/t/f4DzwIpg7T/mUDyHwylDtYWhxkOCSAEfTv nE4v/1v2s7/TO+IFVyY345mMi5X7S8z7dCxBdoVkMr3U9hxcCqNbnRM0d8YkgLNt31 KY9g3zNaPyicrMUG+zTXKaCfAVczYqOHAGSTlrxOYICUDjwGUmL4Mm5/Y1pA5d5erP 2B3o+lYtEw3dXQvmeZrINuy5g4wVrshRkC9/b1Wyta4XNHyoXRtEK+7ffgL6krRbI6 Ct8Zj3qMFAzmw== From: Maxime Ripard To: Daniel Vetter , David Airlie , Maarten Lankhorst , Thomas Zimmermann , Maxime Ripard Subject: [PATCH v2 2/5] drm/atomic: Remove inexistent reference Date: Thu, 14 Dec 2023 11:09:13 +0100 Message-ID: <20231214100917.277842-2-mripard@kernel.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20231214100917.277842-1-mripard@kernel.org> References: <20231214100917.277842-1-mripard@kernel.org> MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Sui Jingfeng , Pekka Paalanen , dri-devel@lists.freedesktop.org Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Commit 63e83c1dba54 ("drm: Consolidate connector arrays in drm_atomic_state") removed the connector_states field but didn't remove its mention in the num_connectors documentation. Acked-by: Sui Jingfeng Reviewed-by: Daniel Vetter Signed-off-by: Maxime Ripard --- include/drm/drm_atomic.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h index 2a08030fcd75..13cecdc1257d 100644 --- a/include/drm/drm_atomic.h +++ b/include/drm/drm_atomic.h @@ -413,7 +413,7 @@ struct drm_atomic_state { struct __drm_crtcs_state *crtcs; /** - * @num_connector: size of the @connectors and @connector_states arrays + * @num_connector: size of the @connectors array */ int num_connector; From patchwork Thu Dec 14 10:09:14 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxime Ripard X-Patchwork-Id: 13492697 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 250F8C4332F for ; Thu, 14 Dec 2023 10:09:35 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 3DC7110E8F9; Thu, 14 Dec 2023 10:09:33 +0000 (UTC) Received: from sin.source.kernel.org (sin.source.kernel.org [IPv6:2604:1380:40e1:4800::1]) by gabe.freedesktop.org (Postfix) with ESMTPS id 5CAF910E906 for ; Thu, 14 Dec 2023 10:09:29 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sin.source.kernel.org (Postfix) with ESMTP id 9A81ACE2270; Thu, 14 Dec 2023 10:09:27 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 84DAEC433C7; Thu, 14 Dec 2023 10:09:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1702548566; bh=H209USp+BPkGA8SeKFE6v91ToS7a7y8PB9+ctzoobn0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YRbhxXt5n99dUCpctoff+UWkOC1yoVfTFXEVGlKFhHVbkN6BWN6mL9vHaUIL5cD4M d+YTfQLP9B5j7tnZvGRZ2D+0H0IEpnuZLqE3mTQXgpu2JoqFcSWLB6pG04UDevgmfq Sfd2ki14T0FFfd2pBUrYg76+jKGZX9RO0Vt8YGLU/7leflH6bbPmBkcl7qJPsVU511 rT6LWdJiepFd1Naj8IY0hU7PKnBrjFSqc+Hp752PGkpevDNKqvvNgJeRmOdSpSS+25 TeMiP8v9SuwbTAP7Ykvee6iKsqWiS90n6OO7UM3HNRN3rlvNSEjLaFb5/WDYm9SA5V i+CHT90RmQQqg== From: Maxime Ripard To: Daniel Vetter , David Airlie , Maarten Lankhorst , Thomas Zimmermann , Maxime Ripard Subject: [PATCH v2 3/5] drm/atomic: Rework the object doc a bit Date: Thu, 14 Dec 2023 11:09:14 +0100 Message-ID: <20231214100917.277842-3-mripard@kernel.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20231214100917.277842-1-mripard@kernel.org> References: <20231214100917.277842-1-mripard@kernel.org> MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Sui Jingfeng , Pekka Paalanen , dri-devel@lists.freedesktop.org Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Commits 63e83c1dba54 ("drm: Consolidate connector arrays in drm_atomic_state"), b8b5342b699b ("drm: Consolidate plane arrays in drm_atomic_state") and 5d943aa6c0d4 ("drm: Consolidate crtc arrays in drm_atomic_state") moved the object pointer and their state pointer to an intermediate structure storing both. The CRTC commit didn't update the doc of the crtcs field to reflect that, and the doc for the planes and connectors fields mention that they are pointers to an array of structures with per-$OBJECT data. The private_objs field was added later on by commit b430c27a7de3 ("drm: Add driver-private objects to atomic state") reusing the same sentence than the crtcs field, probably due to copy and paste. While these fields are indeed pointers to an array, each item of that array contain a pointer to the object structure affected by the update, and its old and new state. There's no per-object data there, and there's more than just a pointer to the objects. Let's rephrase those fields a bit to better match the current situation. Acked-by: Sui Jingfeng Reviewed-by: Daniel Vetter Signed-off-by: Maxime Ripard --- include/drm/drm_atomic.h | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h index 13cecdc1257d..914574b58ae7 100644 --- a/include/drm/drm_atomic.h +++ b/include/drm/drm_atomic.h @@ -403,12 +403,18 @@ struct drm_atomic_state { bool duplicated : 1; /** - * @planes: pointer to array of structures with per-plane data + * @planes: + * + * Pointer to array of @drm_plane and @drm_plane_state part of this + * update. */ struct __drm_planes_state *planes; /** - * @crtcs: pointer to array of CRTC pointers + * @crtcs: + * + * Pointer to array of @drm_crtc and @drm_crtc_state part of this + * update. */ struct __drm_crtcs_state *crtcs; @@ -418,7 +424,10 @@ struct drm_atomic_state { int num_connector; /** - * @connectors: pointer to array of structures with per-connector data + * @connectors: + * + * Pointer to array of @drm_connector and @drm_connector_state part of + * this update. */ struct __drm_connnectors_state *connectors; @@ -428,7 +437,10 @@ struct drm_atomic_state { int num_private_objs; /** - * @private_objs: pointer to array of private object pointers + * @private_objs: + * + * Pointer to array of @drm_private_obj and @drm_private_obj_state part + * of this update. */ struct __drm_private_objs_state *private_objs; From patchwork Thu Dec 14 10:09:15 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxime Ripard X-Patchwork-Id: 13492699 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id B7CC6C4332F for ; Thu, 14 Dec 2023 10:09:43 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 1B5C810E918; Thu, 14 Dec 2023 10:09:42 +0000 (UTC) Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by gabe.freedesktop.org (Postfix) with ESMTPS id 195D110E911 for ; Thu, 14 Dec 2023 10:09:31 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id 551626216A; Thu, 14 Dec 2023 10:09:30 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A444DC433C7; Thu, 14 Dec 2023 10:09:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1702548570; bh=5bqkfAelbOTqlj5Ldp8Y2gweUJ+1X2cnM1h4FqoT81E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=jig6IJ2m6JI9PvNPwgL1UnLjpkqTkTKDtMGl3w4StOKNRS9250mkgr0LgwPHmP0wW 4Et9rWN5C/EeY8AhRZibmHhBwDox7TYMCAMfBI+mj1AP0JQWS0LMCgX/f9wf/gxlrg 2SO1D9AtTcshCEPptFVJNjUGRm8nLSbV6Z5iBjZru+woy1QNmpovcZzgAypljGRILY ks4KNC9oUl9UH+VUYta9hygzdZivthoYaNaqTIkKdqkvJGB47QIz7HNOC6gzpCAUN/ nsBIfdDWfV8OQYb4hjkU9Y3uGakoL2GxtrKor7IT3xSJWEkXdzRPWIT48GsxnZ6CVW NnP3mOiHy34bQ== From: Maxime Ripard To: Daniel Vetter , David Airlie , Maarten Lankhorst , Thomas Zimmermann , Maxime Ripard Subject: [PATCH v2 4/5] drm/atomic: Make the drm_atomic_state documentation less ambiguous Date: Thu, 14 Dec 2023 11:09:15 +0100 Message-ID: <20231214100917.277842-4-mripard@kernel.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20231214100917.277842-1-mripard@kernel.org> References: <20231214100917.277842-1-mripard@kernel.org> MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Pekka Paalanen , dri-devel@lists.freedesktop.org Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" The current documentation of drm_atomic_state says that it's the "global state object". This is confusing since, while it does contain all the objects affected by an update and their respective states, if an object isn't affected by this update it won't be part of it. Thus, it's not truly a "global state", unlike object state structures that do contain the entire state of a given object. Signed-off-by: Maxime Ripard Reviewed-by: Hamza Mahfooz Acked-by: Pekka Paalanen --- include/drm/drm_atomic.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/include/drm/drm_atomic.h b/include/drm/drm_atomic.h index 914574b58ae7..5df67e587816 100644 --- a/include/drm/drm_atomic.h +++ b/include/drm/drm_atomic.h @@ -346,7 +346,13 @@ struct __drm_private_objs_state { }; /** - * struct drm_atomic_state - the global state object for atomic updates + * struct drm_atomic_state - Atomic commit structure + * + * This structure is the kernel counterpart of @drm_mode_atomic and represents + * an atomic commit that transitions from an old to a new display state. It + * contains all the objects affected by an atomic commits and both the new + * state structures and pointers to the old state structures for + * these. * * States are added to an atomic update by calling drm_atomic_get_crtc_state(), * drm_atomic_get_plane_state(), drm_atomic_get_connector_state(), or for From patchwork Thu Dec 14 10:09:16 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxime Ripard X-Patchwork-Id: 13492700 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from gabe.freedesktop.org (gabe.freedesktop.org [131.252.210.177]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id DA734C4167B for ; Thu, 14 Dec 2023 10:09:47 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 138D010E906; Thu, 14 Dec 2023 10:09:47 +0000 (UTC) Received: from dfw.source.kernel.org (dfw.source.kernel.org [IPv6:2604:1380:4641:c500::1]) by gabe.freedesktop.org (Postfix) with ESMTPS id C515F10E906 for ; Thu, 14 Dec 2023 10:09:33 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id 1922E6216A; Thu, 14 Dec 2023 10:09:33 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 69114C433C7; Thu, 14 Dec 2023 10:09:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1702548572; bh=sj83K/4JenSCs5c0jZW5byPMqZx5MToX9bHZtccVSfU=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=X5gtxfxYXKYydFks9OeLo6P5GxcARPpatR86VYI94yIYRwJdpaviZ3/dvu2eHDIx/ VUCkWdO0n0EZECaOLGnPgSM1JgSIBSfdwTz0iJWJlAslSbtk7yexUy0H4mjRTsgPKC BeROysdCui/NoI+LyG0QkVqoRtgPMFsF30j3ZxImiv64H+Axo+O16W3DYTHFTtpt0G vxM2MTouohUqYgTIgJej3wPxJOm0okSt9yFXt+KWUEpYxYXSBWwkgIuBNQmVJEqDCo VBRMF8PA9y9iBt8nxluqRWTXQvkRQOW16QIcoznID140ehWM5PvAkt5vZ5k2z16AjP odm+C7vOVyqGg== From: Maxime Ripard To: Daniel Vetter , David Airlie , Maarten Lankhorst , Thomas Zimmermann , Maxime Ripard Subject: [PATCH v2 5/5] drm/todo: Add entry to rename drm_atomic_state Date: Thu, 14 Dec 2023 11:09:16 +0100 Message-ID: <20231214100917.277842-5-mripard@kernel.org> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20231214100917.277842-1-mripard@kernel.org> References: <20231214100917.277842-1-mripard@kernel.org> MIME-Version: 1.0 X-BeenThere: dri-devel@lists.freedesktop.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Direct Rendering Infrastructure - Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Pekka Paalanen , dri-devel@lists.freedesktop.org Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" The name of the structure drm_atomic_state is confusing. Let's add an entry to our todo list to rename it. Reviewed-by: Daniel Vetter Signed-off-by: Maxime Ripard --- Documentation/gpu/todo.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst index 41a264bf84ce..fb9ad120b141 100644 --- a/Documentation/gpu/todo.rst +++ b/Documentation/gpu/todo.rst @@ -120,6 +120,29 @@ Contact: Daniel Vetter, respective driver maintainers Level: Advanced +Rename drm_atomic_state +----------------------- + +The KMS framework uses two slightly different definitions for the ``state`` +concept. For a given object (plane, CRTC, encoder, etc., so +``drm_$OBJECT_state``), the state is the entire state of that object. However, +at the device level, ``drm_atomic_state`` refers to a state update for a +limited number of objects. + +The state isn't the entire device state, but only the full state of some +objects in that device. This is confusing to newcomers, and +``drm_atomic_state`` should be renamed to something clearer like +``drm_atomic_commit``. + +In addition to renaming the structure itself, it would also imply renaming some +related functions (``drm_atomic_state_alloc``, ``drm_atomic_state_get``, +``drm_atomic_state_put``, ``drm_atomic_state_init``, +``__drm_atomic_state_free``, etc.). + +Contact: Maxime Ripard + +Level: Advanced + Fallout from atomic KMS -----------------------