From patchwork Thu Jun 15 13:27:34 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mark Rutland X-Patchwork-Id: 108520 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a59:994d:0:b0:3d9:f83d:47d9 with SMTP id k13csp640719vqr; Thu, 15 Jun 2023 06:36:02 -0700 (PDT) X-Google-Smtp-Source: ACHHUZ60RhK1YJgbMUohMSw8ir2Qbhnd3Wv+e5shm66XT5K0olWP3ZXOHkQ+QA4Elui+GhNSohMo X-Received: by 2002:a17:902:c649:b0:1b2:4ece:55f1 with SMTP id s9-20020a170902c64900b001b24ece55f1mr12398875pls.35.1686836161965; Thu, 15 Jun 2023 06:36:01 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1686836161; cv=none; d=google.com; s=arc-20160816; b=IdrqcHIaaW610MIz8m9qFYtkTVqG2xjpSxhF3T5AwkvFth5I8sr0NElQPf637MRnLb 5Ry0bq2F7NpCSh2rERFQG/64i0NvrpJTdcv/LjwVrCJtqv7MPFrKU9fL5V7Miz7U/Fi6 tJa1y3r9CkQ/yFkzWiizVc9H1AEywt8IikwNMj57sTDOlmEED/drK6e3i1qt2v1cMpbu KgFG32mEy6JRlThYudmcp8K7GWfBJ3jFd98YlemsWuK9VdJUN1DJhUj5xFOhvWd9PeJ0 j+OsyZ6AUha09n6szoKMvULUMBPrsBJXuti11OtfcrU5dSzH34yv5UMYtJI9cv2LzGwg mgog== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:content-transfer-encoding:mime-version :message-id:date:subject:cc:to:from; bh=gZLCXAkWzy66R80HRuqNzdB8xCRCDU43NQTBc1r2pQc=; b=fUUP5hYOd7GUg2A1A0wwW3jKuRxjMX9I9Hmj4AvEryS0bwjSdf2w2p0cm74lgpEzJw 8RajtciDCn2L9yvZe4v2eAJzA3m915bWK6DGEzeMdWH/b4tN4yeSJWG9dhNlqv1iOFZI xsh3inEuXJHv3uwDHZJXoOBaoCK+ml80ixoAhnxkd3ioKpotsJajC/6tH1lE6Zonxg+X c8JHtVujrwi69YaBD5WjH1ZN8ARSHXzN+AdGIY7JtJMc4R3DWQbE/EpeZgC5Wt0bKQNb gi3IZZsC9PDsUR2nWoJCxkpbE55wxTaomP1HANZg/7tFdPQUZiJ7xYutF3K/as18LxAx I4+w== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=arm.com Received: from out1.vger.email (out1.vger.email. [2620:137:e000::1:20]) by mx.google.com with ESMTP id kb14-20020a170903338e00b001b02390367fsi4008044plb.595.2023.06.15.06.35.49; Thu, 15 Jun 2023 06:36:01 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20; Authentication-Results: mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=arm.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230423AbjFON1r (ORCPT + 99 others); Thu, 15 Jun 2023 09:27:47 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39802 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S241371AbjFON1o (ORCPT ); Thu, 15 Jun 2023 09:27:44 -0400 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by lindbergh.monkeyblade.net (Postfix) with ESMTP id 5972D273C for ; Thu, 15 Jun 2023 06:27:42 -0700 (PDT) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 1D7A71FB; Thu, 15 Jun 2023 06:28:26 -0700 (PDT) Received: from lakrids.cambridge.arm.com (usa-sjc-imap-foss1.foss.arm.com [10.121.207.14]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPA id E21B73F64C; Thu, 15 Jun 2023 06:27:40 -0700 (PDT) From: Mark Rutland To: linux-kernel@vger.kernel.org Cc: boqun.feng@gmail.com, keescook@chromium.org, mark.rutland@arm.com, paulmck@kernel.org, peterz@infradead.org, will@kernel.org Subject: [PATCH] locking/atomic: scripts: fix ${atomic}_dec_if_positive() kerneldoc Date: Thu, 15 Jun 2023 14:27:34 +0100 Message-Id: <20230615132734.1119765-1-mark.rutland@arm.com> X-Mailer: git-send-email 2.30.2 MIME-Version: 1.0 X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_MED, SPF_HELO_NONE,SPF_NONE,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on lindbergh.monkeyblade.net Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org X-getmail-retrieved-from-mailbox: =?utf-8?q?INBOX?= X-GMAIL-THRID: =?utf-8?q?1768775914928793020?= X-GMAIL-MSGID: =?utf-8?q?1768775914928793020?= The ${atomic}_dec_if_positive() ops are unlike all the other conditional atomic ops. Rather than returning a boolean success value, these return the value that the atomic variable would be updated to, even when no update is performed. We missed this when adding kerneldoc comments, and the documentation for ${atomic}_dec_if_positive() erroneously states: | Return: @true if @v was updated, @false otherwise. Ideally we'd clean this up by aligning ${atomic}_dec_if_positive() with the usual atomic op conventions: with ${atomic}_fetch_dec_if_positive() for those who care about the value of the varaible, and ${atomic}_dec_if_positive() returning a boolean success value. In the mean time, align the documentation with the current reality. Fixes: ad8110706f381170 ("locking/atomic: scripts: generate kerneldoc comments") Signed-off-by: Mark Rutland Cc: Boqun Feng Cc: Kees Cook Cc: Paul E. McKenney Cc: Peter Zijlstra Cc: Will Deacon Reviewed-by: Paul E. McKenney --- include/linux/atomic/atomic-arch-fallback.h | 6 +++--- include/linux/atomic/atomic-instrumented.h | 8 ++++---- include/linux/atomic/atomic-long.h | 4 ++-- scripts/atomic/kerneldoc/dec_if_positive | 2 +- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/include/linux/atomic/atomic-arch-fallback.h b/include/linux/atomic/atomic-arch-fallback.h index 8cded57dd7a6f..18f5744dfb5d8 100644 --- a/include/linux/atomic/atomic-arch-fallback.h +++ b/include/linux/atomic/atomic-arch-fallback.h @@ -2520,7 +2520,7 @@ raw_atomic_dec_unless_positive(atomic_t *v) * * Safe to use in noinstr code; prefer atomic_dec_if_positive() elsewhere. * - * Return: @true if @v was updated, @false otherwise. + * Return: The old value of (@v - 1), regardless of whether @v was updated. */ static __always_inline int raw_atomic_dec_if_positive(atomic_t *v) @@ -4636,7 +4636,7 @@ raw_atomic64_dec_unless_positive(atomic64_t *v) * * Safe to use in noinstr code; prefer atomic64_dec_if_positive() elsewhere. * - * Return: @true if @v was updated, @false otherwise. + * Return: The old value of (@v - 1), regardless of whether @v was updated. */ static __always_inline s64 raw_atomic64_dec_if_positive(atomic64_t *v) @@ -4657,4 +4657,4 @@ raw_atomic64_dec_if_positive(atomic64_t *v) } #endif /* _LINUX_ATOMIC_FALLBACK_H */ -// 3916f02c038baa3f5190d275f68b9211667fcc9d +// 202b45c7db600ce36198eb1f1fc2c2d5268ace2d diff --git a/include/linux/atomic/atomic-instrumented.h b/include/linux/atomic/atomic-instrumented.h index ebfc795f921b9..d401b406ef7c4 100644 --- a/include/linux/atomic/atomic-instrumented.h +++ b/include/linux/atomic/atomic-instrumented.h @@ -1570,7 +1570,7 @@ atomic_dec_unless_positive(atomic_t *v) * * Unsafe to use in noinstr code; use raw_atomic_dec_if_positive() there. * - * Return: @true if @v was updated, @false otherwise. + * Return: The old value of (@v - 1), regardless of whether @v was updated. */ static __always_inline int atomic_dec_if_positive(atomic_t *v) @@ -3134,7 +3134,7 @@ atomic64_dec_unless_positive(atomic64_t *v) * * Unsafe to use in noinstr code; use raw_atomic64_dec_if_positive() there. * - * Return: @true if @v was updated, @false otherwise. + * Return: The old value of (@v - 1), regardless of whether @v was updated. */ static __always_inline s64 atomic64_dec_if_positive(atomic64_t *v) @@ -4698,7 +4698,7 @@ atomic_long_dec_unless_positive(atomic_long_t *v) * * Unsafe to use in noinstr code; use raw_atomic_long_dec_if_positive() there. * - * Return: @true if @v was updated, @false otherwise. + * Return: The old value of (@v - 1), regardless of whether @v was updated. */ static __always_inline long atomic_long_dec_if_positive(atomic_long_t *v) @@ -5000,4 +5000,4 @@ atomic_long_dec_if_positive(atomic_long_t *v) #endif /* _LINUX_ATOMIC_INSTRUMENTED_H */ -// 06cec02e676a484857aee38b0071a1d846ec9457 +// 1568f875fef72097413caab8339120c065a39aa4 diff --git a/include/linux/atomic/atomic-long.h b/include/linux/atomic/atomic-long.h index f6df2adadf997..c82947170ddc8 100644 --- a/include/linux/atomic/atomic-long.h +++ b/include/linux/atomic/atomic-long.h @@ -1782,7 +1782,7 @@ raw_atomic_long_dec_unless_positive(atomic_long_t *v) * * Safe to use in noinstr code; prefer atomic_long_dec_if_positive() elsewhere. * - * Return: @true if @v was updated, @false otherwise. + * Return: The old value of (@v - 1), regardless of whether @v was updated. */ static __always_inline long raw_atomic_long_dec_if_positive(atomic_long_t *v) @@ -1795,4 +1795,4 @@ raw_atomic_long_dec_if_positive(atomic_long_t *v) } #endif /* _LINUX_ATOMIC_LONG_H */ -// 029d2e3a493086671e874a4c2e0e42084be42403 +// 4ef23f98c73cff96d239896175fd26b10b88899e diff --git a/scripts/atomic/kerneldoc/dec_if_positive b/scripts/atomic/kerneldoc/dec_if_positive index 7c742866fb6b6..04f1aed3cf830 100644 --- a/scripts/atomic/kerneldoc/dec_if_positive +++ b/scripts/atomic/kerneldoc/dec_if_positive @@ -7,6 +7,6 @@ cat <