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: 879575 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id DBDBB25E471; Wed, 9 Apr 2025 12:07:44 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744200465; cv=none; b=ELYNddHyzRrDJc+2PYwSMbv5v++z/wWRbGOt4pwRcpuYebJP6HCSdNxk+A8OwWQdBs3bC26sg6EuJGYwrfMsp0/QNF5LfgvuIMe5jaRjOgLDrLI26AsikaF6hFSBYPkcxUgmh3Lo3KDkvRRSty32lB4/YVyOs8pr8ZeQkpMNyMU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1744200465; c=relaxed/simple; bh=FdUb0DPDYi+ttgoinI37K88fuRyaVge7JDVXiVilF7E=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=XcNksFkot4tsp9YKxl1KmiF7mC7B3atWiA9KGb0S7PdoJKUDFpEDg/Pom0cbkJ57O+41zt72UWS7oA/KncJf74Ds4nyUV4AbUaMLsQuMbk5uCwng0v4UnES5Tevjc/UV5nJb7de1MBPWarHCDpbNDXynRtV1SO0HMc/Ik+pvuNI= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=GhqxgiUk; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="GhqxgiUk" 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=B6m?= , 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> Precedence: bulk X-Mailing-List: linux-media@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 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)