From patchwork Wed Apr 9 14:50:34 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 14044915 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 90381C369A4 for ; Wed, 9 Apr 2025 14:50:56 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 1573110E926; Wed, 9 Apr 2025 14:50:53 +0000 (UTC) Authentication-Results: gabe.freedesktop.org; dkim=pass (2048-bit key; unprotected) header.d=bootlin.com header.i=@bootlin.com header.b="oxbfpY5d"; dkim-atps=neutral Received: from relay6-d.mail.gandi.net (relay6-d.mail.gandi.net [217.70.183.198]) by gabe.freedesktop.org (Postfix) with ESMTPS id 917AB10E916 for ; Wed, 9 Apr 2025 14:50:48 +0000 (UTC) Received: by mail.gandi.net (Postfix) with ESMTPSA id 9D19E44282; Wed, 9 Apr 2025 14:50:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1744210247; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=KEmrM0VCU/J7ievAToNUp1p2V609oJSHGiAFe/2zZVo=; b=oxbfpY5dUtHCfmiSZUJRPZhC7MQhoIcZO80cG6DM6IRXATITV5jtCO2kv1+TjPCMGu9pnS f4CRqoyhzKukNQV1CRr7QmImhUhmOBwVts/npK4qxw2rNiJH9EZM+lt32/a/cHMhKX0PE5 Fl/tNJhC4u+vNj3hH4++3Rjv5XYOY7keVTNx1+jaJ2CQshTbtKNiNCFYNhjvw4edJ7qwc/ b6vUx3zgwRGZzyEFzNQHZhvThiX3Fvv5/gYtQzD0aYgtJiT70geAik+CDgHbB6JiAaGGoO 7bSJzOygCisM5MLX9FXSZHaOFjSIrkvYIrfxFeS+Xth8rZPDknywUGBfsXlyLA== From: Luca Ceresoli Date: Wed, 09 Apr 2025 16:50:34 +0200 Subject: [PATCH v7 1/2] drm/bridge: documentat bridge allocation and lifecycle MIME-Version: 1.0 Message-Id: <20250409-drm-bridge-alloc-doc-test-v7-1-a3ca4b97597f@bootlin.com> References: <20250409-drm-bridge-alloc-doc-test-v7-0-a3ca4b97597f@bootlin.com> In-Reply-To: <20250409-drm-bridge-alloc-doc-test-v7-0-a3ca4b97597f@bootlin.com> To: Maarten Lankhorst , Maxime Ripard , Thomas Zimmermann , David Airlie , Simona Vetter , Jonathan Corbet , Andrzej Hajda , Neil Armstrong , Robert Foss , Laurent Pinchart , Jonas Karlman , Jernej Skrabec Cc: Anusha Srivatsa , Paul Kocialkowski , Dmitry Baryshkov , =?utf-8?q?Herv=C3=A9_Codina?= , Hui Pu , Thomas Petazzoni , dri-devel@lists.freedesktop.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Luca Ceresoli X-Mailer: b4 0.14.2 X-GND-State: clean X-GND-Score: -100 X-GND-Cause: gggruggvucftvghtrhhoucdtuddrgeefvddrtddtgddvtdeivdelucetufdoteggodetrfdotffvucfrrhhofhhilhgvmecuifetpfffkfdpucggtfgfnhhsuhgsshgtrhhisggvnecuuegrihhlohhuthemuceftddunecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenucfjughrpefhfffugggtgffkfhgjvfevofesthejredtredtjeenucfhrhhomhepnfhutggrucevvghrvghsohhlihcuoehluhgtrgdrtggvrhgvshholhhisegsohhothhlihhnrdgtohhmqeenucggtffrrghtthgvrhhnpeeiieeuvdfftefgueduleehueetgffgjeeitedtteetkeeuueeuueekveevvdeuveenucfkphepvdgrtddvmeeijedtmedvtddvtdemvggrtddumegsvgegudemleehvgejmeefgeefmeeludefvgenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepihhnvghtpedvrgdtvdemieejtdemvddtvddtmegvrgdtudemsggvgedumeelhegvjeemfeegfeemledufegvpdhhvghloheplgduledvrdduieekrddujeekrdduudekngdpmhgrihhlfhhrohhmpehluhgtrgdrtggvrhgvshholhhisegsohhothhlihhnrdgtohhmpdhnsggprhgtphhtthhopedvvddprhgtphhtthhopehlihhnuhigqdhkvghrnhgvlhesvhhgvghrrdhkvghrnhgvlhdrohhrghdprhgtphhtthhopefnrghurhgvnhhtrdhpihhntghhrghrthesihguvggrshhonhgsohgrrhgurdgtohhmpdhrtghpthhtohepnhgvihhlrdgrrhhms hhtrhhonhhgsehlihhnrghrohdrohhrghdprhgtphhtthhopegrnhgurhiivghjrdhhrghjuggrsehinhhtvghlrdgtohhmpdhrtghpthhtohepthhhohhmrghsrdhpvghtrgiiiihonhhisegsohhothhlihhnrdgtohhmpdhrtghpthhtohepjfhuihdrrfhusehgvghhvggrlhhthhgtrghrvgdrtghomhdprhgtphhtthhopehluhhmrghgsehkvghrnhgvlhdrohhrghdprhgtphhtthhopehrfhhoshhssehkvghrnhgvlhdrohhrgh X-GND-Sasl: luca.ceresoli@bootlin.com 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: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Document in detail the DRM bridge allocation and refcounting process based on the recently introduced devm_drm_bridge_alloc(). Signed-off-by: Luca Ceresoli --- Changes in v7: - remove mention of "legacy mode", we now support only refcounted bridges - rename patch title from "drm/bridge: add documentation of refcounted bridges", we now support only refcounted bridges Changes in v6: - update to the new devm_drm_bridge_alloc() API - rewrite and improve various sentences for clarity - fix typos (Randy Dunlap) This patch was added in v5. --- Documentation/gpu/drm-kms-helpers.rst | 6 +++ drivers/gpu/drm/drm_bridge.c | 73 +++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) diff --git a/Documentation/gpu/drm-kms-helpers.rst b/Documentation/gpu/drm-kms-helpers.rst index 5139705089f200b189876a5a61bf2a935cec433a..393cd0e4cb5af3fe98674e7a96c853ffb2556c97 100644 --- a/Documentation/gpu/drm-kms-helpers.rst +++ b/Documentation/gpu/drm-kms-helpers.rst @@ -151,6 +151,12 @@ Overview .. kernel-doc:: drivers/gpu/drm/drm_bridge.c :doc: overview +Bridge allocation and lifecycle +------------------------------- + +.. kernel-doc:: drivers/gpu/drm/drm_bridge.c + :doc: bridge lifecycle + Display Driver Integration -------------------------- diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c index b4c89ec01998b849018ce031c7cd84614e65e710..b7e1ad761dad52bdb2ec09d425e69ee23a18fd36 100644 --- a/drivers/gpu/drm/drm_bridge.c +++ b/drivers/gpu/drm/drm_bridge.c @@ -61,6 +61,79 @@ * encoder chain. */ +/** + * DOC: bridge lifecycle + * + * In some use cases such as hot-plugging a DRM bridge device can + * physically disappear and reappear at runtime. To handle such cases + * without destroying and recreating the entire DRM pipeline, DRM bridge + * lifetime is managed using reference counting: + * + * - each &struct drm_bridge is reference counted since its allocation + * - any code taking a pointer to a bridge has APIs to get a reference and + * put it when done, to ensure the memory allocated for the bridge won't + * be deallocated while there is still a reference to it + * - the driver implementing the bridge also holds a reference, but the + * allocated struct can survive the driver in case other references still + * exist + * - deallocation is done when the last put happens, dropping the refcount + * to zero + * + * Usage of refcounted bridges happens in two sides: the bridge *provider* + * and the bridge *consumers*. The bridge provider is the driver + * implementing the bridge. The bridge consumers are all parts of the + * kernel taking a &struct drm_bridge pointer, including other bridges, + * encoders and the DRM core. + * + * For bridge **providers**, the bridge driver declares a driver-specific + * struct embedding a &struct drm_bridge. E.g.:: + * + * struct my_bridge { + * ... + * struct drm_bridge bridge; + * ... + * }; + * + * The driver must allocate and initialize ``struct my_bridge`` using + * devm_drm_bridge_alloc(), as in this example:: + * + * static int my_bridge_probe(...) + * { + * struct device *dev = ...; + * struct my_bridge *mybr; + * + * mybr = devm_drm_bridge_alloc(dev, struct my_bridge, bridge, &my_bridge_funcs); + * if (IS_ERR(mybr)) + * return PTR_ERR(mybr); + * + * // Get resources, initialize my_bridge members... + * drm_bridge_add(&mybr->bridge); + * ... + * } + * + * static void my_bridge_remove(...) + * { + * struct my_bridge *mybr = ...; + * + * drm_bridge_remove(&mybr->bridge); + * // Free resources + * // ... NO kfree here! + * } + * + * Bridge **consumers** need to handle the case of a bridge being removed + * while they have a pointer to it. As this can happen at any time, such + * code can incur in use-after-free. To avoid that, consumers have to call + * drm_bridge_get() when taking a pointer and drm_bridge_put() after they + * are done using it. This will extend the allocation lifetime of the + * bridge struct until the last reference has been put, potentially a long + * time after the bridge device has been removed from the kernel. + * + * Functions that return a pointer to a bridge, such as + * of_drm_find_bridge(), internally call drm_bridge_get() on the bridge + * they are about to return, so users using such functions to get a bridge + * pointer only have to take care of calling drm_bridge_put(). + */ + /** * DOC: display driver integration * From patchwork Wed Apr 9 14:50:35 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Luca Ceresoli X-Patchwork-Id: 14044914 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 E8CDBC36002 for ; Wed, 9 Apr 2025 14:50:54 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 65F4A10E923; Wed, 9 Apr 2025 14:50:52 +0000 (UTC) Authentication-Results: gabe.freedesktop.org; dkim=pass (2048-bit key; unprotected) header.d=bootlin.com header.i=@bootlin.com header.b="ijoqRPOi"; dkim-atps=neutral Received: from relay6-d.mail.gandi.net (relay6-d.mail.gandi.net [217.70.183.198]) by gabe.freedesktop.org (Postfix) with ESMTPS id 6499B10E916 for ; Wed, 9 Apr 2025 14:50:50 +0000 (UTC) Received: by mail.gandi.net (Postfix) with ESMTPSA id 70E024427E; Wed, 9 Apr 2025 14:50:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1744210249; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Mzm1JuGkocIsGBpNPmA5oKl0NqM4cvm2NKtV1oMF3eQ=; b=ijoqRPOijtHQVSqqM/gfbkTeRSVsd5eqPrGNS8JjT+DJ7aqdiD/GWWEdf7CCD2qkPsWZjD tH387B9pU4qb45sOs11AO0mrDCeMo6Mx0XBU3RYmdwUGoYiDNAEO6RrwBZ5spySJ49/QNZ k8WWYIhcCgego2JauCKR/6+zlNLb1/amQUjPIoYzqt+jdJo+L0FU6cZ5JZYd+W4UuGgnMI O8vLbnCDJpAK2vL5dFneqP80lKiuPpI7tViBgqgQQrmuOsC850B+ZU8o+6SaJMleMvUjaf oOlp5cDkRtVfkR/EJCbMCrs7O1P+8GCgStDURNjAHudBr5bx/EayYX+bq1ZTKA== From: Luca Ceresoli Date: Wed, 09 Apr 2025 16:50:35 +0200 Subject: [PATCH v7 2/2] drm/tests: bridge: add a KUnit test for devm_drm_bridge_alloc() MIME-Version: 1.0 Message-Id: <20250409-drm-bridge-alloc-doc-test-v7-2-a3ca4b97597f@bootlin.com> References: <20250409-drm-bridge-alloc-doc-test-v7-0-a3ca4b97597f@bootlin.com> In-Reply-To: <20250409-drm-bridge-alloc-doc-test-v7-0-a3ca4b97597f@bootlin.com> To: Maarten Lankhorst , Maxime Ripard , Thomas Zimmermann , David Airlie , Simona Vetter , Jonathan Corbet , Andrzej Hajda , Neil Armstrong , Robert Foss , Laurent Pinchart , Jonas Karlman , Jernej Skrabec Cc: Anusha Srivatsa , Paul Kocialkowski , Dmitry Baryshkov , =?utf-8?q?Herv=C3=A9_Codina?= , Hui Pu , Thomas Petazzoni , dri-devel@lists.freedesktop.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Luca Ceresoli X-Mailer: b4 0.14.2 X-GND-State: clean X-GND-Score: -100 X-GND-Cause: gggruggvucftvghtrhhoucdtuddrgeefvddrtddtgddvtdeivdelucetufdoteggodetrfdotffvucfrrhhofhhilhgvmecuifetpfffkfdpucggtfgfnhhsuhgsshgtrhhisggvnecuuegrihhlohhuthemuceftddunecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenucfjughrpefhfffugggtgffkfhgjvfevofesthejredtredtjeenucfhrhhomhepnfhutggrucevvghrvghsohhlihcuoehluhgtrgdrtggvrhgvshholhhisegsohhothhlihhnrdgtohhmqeenucggtffrrghtthgvrhhnpeeiieeuvdfftefgueduleehueetgffgjeeitedtteetkeeuueeuueekveevvdeuveenucfkphepvdgrtddvmeeijedtmedvtddvtdemvggrtddumegsvgegudemleehvgejmeefgeefmeeludefvgenucevlhhushhtvghrufhiiigvpedunecurfgrrhgrmhepihhnvghtpedvrgdtvdemieejtdemvddtvddtmegvrgdtudemsggvgedumeelhegvjeemfeegfeemledufegvpdhhvghloheplgduledvrdduieekrddujeekrdduudekngdpmhgrihhlfhhrohhmpehluhgtrgdrtggvrhgvshholhhisegsohhothhlihhnrdgtohhmpdhnsggprhgtphhtthhopedvvddprhgtphhtthhopehlihhnuhigqdhkvghrnhgvlhesvhhgvghrrdhkvghrnhgvlhdrohhrghdprhgtphhtthhopefnrghurhgvnhhtrdhpihhntghhrghrthesihguvggrshhonhgsohgrrhgurdgtohhmpdhrtghpthhtohepnhgvihhlrdgrrhhms hhtrhhonhhgsehlihhnrghrohdrohhrghdprhgtphhtthhopegrnhgurhiivghjrdhhrghjuggrsehinhhtvghlrdgtohhmpdhrtghpthhtohepthhhohhmrghsrdhpvghtrgiiiihonhhisegsohhothhlihhnrdgtohhmpdhrtghpthhtohepjfhuihdrrfhusehgvghhvggrlhhthhgtrghrvgdrtghomhdprhgtphhtthhopehluhhmrghgsehkvghrnhgvlhdrohhrghdprhgtphhtthhopehrfhhoshhssehkvghrnhgvlhdrohhrgh X-GND-Sasl: luca.ceresoli@bootlin.com 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: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" Add a basic KUnit test for the newly introduced drm_bridge_alloc(). Signed-off-by: Luca Ceresoli --- Changed in v7: - rebase on current drm-misc-next, which now has a drm_bridge_test.c file - cleanup commit message Changed in v6: - update to new devm_drm_bridge_alloc() API - remove drm_test_drm_bridge_put test, not straightforward to write with the new API and the current notification mechanism - do not allocate a drm_device: a bridge is allocated without one - rename some identifiers for easier code reading This patch was added in v5. --- drivers/gpu/drm/tests/drm_bridge_test.c | 60 +++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/drivers/gpu/drm/tests/drm_bridge_test.c b/drivers/gpu/drm/tests/drm_bridge_test.c index ff88ec2e911c9cc9a718483f09d4c764f45f991a..87fb64744b67f0780457a546aba77ba945a0ce67 100644 --- a/drivers/gpu/drm/tests/drm_bridge_test.c +++ b/drivers/gpu/drm/tests/drm_bridge_test.c @@ -8,6 +8,7 @@ #include #include +#include #include struct drm_bridge_init_priv { @@ -407,11 +408,70 @@ static struct kunit_suite drm_bridge_helper_reset_crtc_test_suite = { .test_cases = drm_bridge_helper_reset_crtc_tests, }; +struct drm_bridge_alloc_test_ctx { + struct device *dev; +}; + +/* + * Mimick the typical struct defined by a bridge driver, which embeds a + * bridge plus other fields. + */ +struct dummy_drm_bridge { + int dummy; // ensure we test non-zero @bridge offset + struct drm_bridge bridge; +}; + +static const struct drm_bridge_funcs drm_bridge_dummy_funcs = { +}; + +static int drm_test_bridge_alloc_init(struct kunit *test) +{ + struct drm_bridge_alloc_test_ctx *ctx; + + ctx = kunit_kzalloc(test, sizeof(*ctx), GFP_KERNEL); + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx); + + ctx->dev = kunit_device_register(test, "drm-bridge-dev"); + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, ctx->dev); + + test->priv = ctx; + + return 0; +} + +/* + * Test that the allocation and initialization of a bridge works as + * expected and doesn't report any error. + */ +static void drm_test_drm_bridge_alloc(struct kunit *test) +{ + struct drm_bridge_alloc_test_ctx *ctx = test->priv; + struct dummy_drm_bridge *dummy; + + dummy = devm_drm_bridge_alloc(ctx->dev, struct dummy_drm_bridge, bridge, + &drm_bridge_dummy_funcs); + KUNIT_ASSERT_NOT_ERR_OR_NULL(test, dummy); +} + +static struct kunit_case drm_bridge_alloc_tests[] = { + KUNIT_CASE(drm_test_drm_bridge_alloc), + { } +}; + +static struct kunit_suite drm_bridge_alloc_test_suite = { + .name = "drm_bridge_alloc", + .init = drm_test_bridge_alloc_init, + .test_cases = drm_bridge_alloc_tests, +}; + kunit_test_suites( &drm_bridge_get_current_state_test_suite, &drm_bridge_helper_reset_crtc_test_suite, + &drm_bridge_alloc_test_suite, ); MODULE_AUTHOR("Maxime Ripard "); +MODULE_AUTHOR("Luca Ceresoli "); + MODULE_DESCRIPTION("Kunit test for drm_bridge functions"); MODULE_LICENSE("GPL");