[PATCH] percpu_ref: Fix documentation of maximum value

[PATCH] percpu_ref: Fix documentation of maximum value

[Matthew Wilcox (Oracle)]

Tejun changd percpu_ref to use long instead of int back in 2014 but missed
updating this bit of the documentation.  Also add the documentation to
the htmldocs.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 Documentation/driver-api/basics.rst | 3 +++
 include/linux/percpu-refcount.h     | 5 +++--
 lib/percpu-refcount.c               | 2 +-
 3 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index d78b7c328ff7..a3f0a0639053 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -90,6 +90,9 @@ Reference counting
 .. kernel-doc:: lib/refcount.c
    :export:
 
+.. kernel-doc:: include/linux/percpu-refcount.h
+.. kernel-doc:: lib/percpu-refcount.c
+
 Atomics
 -------
 
diff --git a/include/linux/percpu-refcount.h b/include/linux/percpu-refcount.h
index d73a1c08c3e3..1e3212e2c827 100644
--- a/include/linux/percpu-refcount.h
+++ b/include/linux/percpu-refcount.h
@@ -12,8 +12,8 @@
  * start shutting down you call percpu_ref_kill() _before_ dropping the initial
  * refcount.
  *
- * The refcount will have a range of 0 to ((1U << 31) - 1), i.e. one bit less
- * than an atomic_t - this is because of the way shutdown works, see
+ * The refcount will have a range of 0 to LONG_MAX, i.e. one bit less
+ * than an atomic_long_t - this is because of the way shutdown works, see
  * percpu_ref_kill()/PERCPU_COUNT_BIAS.
  *
  * Before you call percpu_ref_kill(), percpu_ref_put() does not check for the
@@ -269,6 +269,7 @@ static inline bool percpu_ref_tryget(struct percpu_ref *ref)
 /**
  * percpu_ref_tryget_live_rcu - same as percpu_ref_tryget_live() but the
  * caller is responsible for taking RCU.
+ * @ref: percpu_ref to try-get
  *
  * This function is safe to call as long as @ref is between init and exit.
  */
diff --git a/lib/percpu-refcount.c b/lib/percpu-refcount.c
index 668f6aa6a75d..dfb9faa4ba83 100644
--- a/lib/percpu-refcount.c
+++ b/lib/percpu-refcount.c
@@ -289,7 +289,7 @@ static void __percpu_ref_switch_mode(struct percpu_ref *ref,
  * @confirm_switch: optional confirmation callback
  *
  * There's no reason to use this function for the usual reference counting.
- * Use percpu_ref_kill[_and_confirm]().
+ * Use percpu_ref_kill() or percpu_ref_kill_and_confirm().
  *
  * Schedule switching of @ref to atomic mode.  All its percpu counts will
  * be collected to the main atomic counter.  On completion, when all CPUs
-- 
2.45.2

Re: [PATCH] percpu_ref: Fix documentation of maximum value

[Tejun Heo]

On Wed, Dec 11, 2024 at 08:40:14PM +0000, Matthew Wilcox (Oracle) wrote:
> Tejun changd percpu_ref to use long instead of int back in 2014 but missed
> updating this bit of the documentation.  Also add the documentation to
> the htmldocs.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

Woof, ten years already.

Acked-by: Tejun Heo <tj@kernel.org>

Thanks.

-- 
tejun