From patchwork Wed Apr 9 12:06:38 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Philipp Stanner X-Patchwork-Id: 14044520 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 DEF9CC369A2 for ; Wed, 9 Apr 2025 12:07:46 +0000 (UTC) Received: from gabe.freedesktop.org (localhost [127.0.0.1]) by gabe.freedesktop.org (Postfix) with ESMTP id 4CB8210E864; Wed, 9 Apr 2025 12:07:46 +0000 (UTC) Authentication-Results: gabe.freedesktop.org; dkim=pass (2048-bit key; unprotected) header.d=kernel.org header.i=@kernel.org header.b="GhqxgiUk"; dkim-atps=neutral Received: from tor.source.kernel.org (tor.source.kernel.org [172.105.4.254]) by gabe.freedesktop.org (Postfix) with ESMTPS id 3B85610E86A; Wed, 9 Apr 2025 12:07:45 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by tor.source.kernel.org (Postfix) with ESMTP id DDEDD615EB; Wed, 9 Apr 2025 12:07:34 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id A3DACC4CEE7; Wed, 9 Apr 2025 12:07:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1744200464; bh=FdUb0DPDYi+ttgoinI37K88fuRyaVge7JDVXiVilF7E=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=GhqxgiUktLqE62NnlGbCozLGAOy1ebYKCfRTbO1C2V8isrEUvyivtHWOlIWWY3iNe lT7qBhQi0YUXEHd/a3nybBs+okp72WCBqbBHa/gUT5qc5stTjpZBUhmQIEvTFikt5z 3QEX/nurLaDWBdA3+xqEX+t36u0MD+4s/DDnE947U63BOSLACxJE4ATzBnB7162kEM uJVlOhBR6ng/gxrCkIJmx2DVTmwcGtpsyRWe122qGV/9UBAusoKc1mqJjzRiizRz4e qqynMSOHuqVH/gL+pm4QM8yBcDL9Jr5dx5FDs1H6jkyRMDbX2Cuq8465NG5c4c31Ao m0BWGZ8ZfmD1w== From: Philipp Stanner To: Sumit Semwal , Gustavo Padovan , =?utf-8?q?Christian_K=C3=B6nig?= , Felix Kuehling , Alex Deucher , Xinhui Pan , David Airlie , Simona Vetter , Maarten Lankhorst , Maxime Ripard , Thomas Zimmermann , Lucas Stach , Russell King , Christian Gmeiner , Jani Nikula , Joonas Lahtinen , Rodrigo Vivi , Tvrtko Ursulin , Frank Binns , Matt Coster , Qiang Yu , Rob Clark , Sean Paul , Konrad Dybcio , Abhinav Kumar , Dmitry Baryshkov , Marijn Suijten , Lyude Paul , Danilo Krummrich , Boris Brezillon , Rob Herring , Steven Price , Dave Airlie , Gerd Hoffmann , Matthew Brost , Philipp Stanner , Huang Rui , Matthew Auld , Melissa Wen , =?utf-8?q?Ma=C3=ADra_Canal?= , Zack Rusin , Broadcom internal kernel review list , Lucas De Marchi , =?utf-8?q?Thomas_Hellstr=C3=B6?= =?utf-8?q?m?= , Bas Nieuwenhuizen , Yang Wang , Jesse Zhang , Tim Huang , Sathishkumar S , Saleemkhan Jamadar , Sunil Khatri , Lijo Lazar , Hawking Zhang , Ma Jun , Yunxiang Li , Eric Huang , Asad Kamal , Srinivasan Shanmugam , Jack Xiao , Friedrich Vock , =?utf-8?q?Michel_D=C3=A4nzer?= , Geert Uytterhoeven , Anna-Maria Behnsen , Thomas Gleixner , Frederic Weisbecker , Dan Carpenter Cc: linux-media@vger.kernel.org, dri-devel@lists.freedesktop.org, linaro-mm-sig@lists.linaro.org, linux-kernel@vger.kernel.org, amd-gfx@lists.freedesktop.org, etnaviv@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, lima@lists.freedesktop.org, linux-arm-msm@vger.kernel.org, freedreno@lists.freedesktop.org, nouveau@lists.freedesktop.org, virtualization@lists.linux.dev, spice-devel@lists.freedesktop.org, intel-xe@lists.freedesktop.org Subject: [PATCH 2/2] dma-fence: Improve docu for dma_fence_check_and_signal() Date: Wed, 9 Apr 2025 14:06:38 +0200 Message-ID: <20250409120640.106408-4-phasta@kernel.org> X-Mailer: git-send-email 2.48.1 In-Reply-To: <20250409120640.106408-2-phasta@kernel.org> References: <20250409120640.106408-2-phasta@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: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" The documentation of the return value of dma_fence_check_and_signal() and dma_fence_check_and_signal_locked() reads as if the returned boolean only describes whether dma_fence_signal() (or similar) has been called before this function call already. That's not the case, since dma_fence_ops.signaled() usually just checks through the sequence number whether the hardware is finished with a fence. That doesn't mean a signaling function has been called already. Make the documentation clearer. Move the Return: documentation to the end, since that's the officially recommended docu style. Signed-off-by: Philipp Stanner --- include/linux/dma-fence.h | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/include/linux/dma-fence.h b/include/linux/dma-fence.h index dc2ad171458b..3df370b2cc7c 100644 --- a/include/linux/dma-fence.h +++ b/include/linux/dma-fence.h @@ -385,14 +385,21 @@ void dma_fence_enable_sw_signaling(struct dma_fence *fence); * dma_fence_check_and_signal_locked - Checks a fence and signals it if necessary * @fence: the fence to check * - * Returns true if the fence was already signaled, false if not. Since this - * function doesn't enable signaling, it is not guaranteed to ever return - * true if dma_fence_add_callback(), dma_fence_wait() or + * Checks whether the fence was already signaled, and, if not, whether + * &struct dma_fence_ops.signaled indicates that it should be signaled. If so, + * the fence gets signaled here. + * + * Since this function doesn't enable signaling, it is not guaranteed to ever + * return true if dma_fence_add_callback(), dma_fence_wait() or * dma_fence_enable_sw_signaling() haven't been called before. * * This function requires &dma_fence.lock to be held. * * See also dma_fence_check_and_signal(). + * + * Return: true if the fence was already signaled, or if + * &struct dma_fence_ops.signaled is implemented and indicates that this fence + * can be treated as signaled; false otherwise. */ static inline bool dma_fence_check_and_signal_locked(struct dma_fence *fence) @@ -412,9 +419,12 @@ dma_fence_check_and_signal_locked(struct dma_fence *fence) * dma_fence_check_and_signal - Checks a fence and signals it if necessary * @fence: the fence to check * - * Returns true if the fence was already signaled, false if not. Since this - * function doesn't enable signaling, it is not guaranteed to ever return - * true if dma_fence_add_callback(), dma_fence_wait() or + * Checks whether the fence was already signaled, and, if not, whether + * &struct dma_fence_ops.signaled indicates that it should be signaled. If so, + * the fence gets signaled here. + * + * Since this function doesn't enable signaling, it is not guaranteed to ever + * return true if dma_fence_add_callback(), dma_fence_wait() or * dma_fence_enable_sw_signaling() haven't been called before. * * It's recommended for seqno fences to call dma_fence_signal when the @@ -423,6 +433,10 @@ dma_fence_check_and_signal_locked(struct dma_fence *fence) * value of this function before calling hardware-specific wait instructions. * * See also dma_fence_check_and_signal_locked(). + * + * Return: true if the fence was already signaled, or if + * &struct dma_fence_ops.signaled is implemented and indicates that this fence + * can be treated as signaled; false otherwise. */ static inline bool dma_fence_check_and_signal(struct dma_fence *fence)