Message-ID: <20171130013646.GA22858@beast>
Date:   Wed, 29 Nov 2017 17:36:46 -0800
From:   Kees Cook <keescook@...omium.org>
To:     Elena Reshetova <elena.reshetova@...el.com>
Cc:     peterz@...radead.org, david@...morbit.com,
        linux-kernel@...r.kernel.org, linux-doc@...r.kernel.org,
        Jonathan Corbet <corbet@....net>
Subject: [PATCH] docs: Expand refcount_t documentation

This updates basics.rst to include refcount_t so it can be referenced by
other .rst files, fixes a kernel-doc typo in refcount.h so the struct
will be documented, and enhances the markup of the refcount-vs-atomic doc.

Signed-off-by: Kees Cook <keescook@...omium.org>
---
This builds on the "refcount-vs-atomic.rst" patch...

Elena, feel free to fold this into your refcount_t doc. Future revisions
should likely get sent to Jon Corbet and CC linux-doc.
---
 Documentation/core-api/refcount-vs-atomic.rst | 84 ++++++++++++++++-----------
 Documentation/driver-api/basics.rst           | 21 +++++--
 include/linux/refcount.h                      |  2 +-
 3 files changed, 67 insertions(+), 40 deletions(-)

diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
index 5619d486e70e..315d5f882331 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -2,11 +2,16 @@
 refcount_t API compared to atomic_t
 ===================================
 
+.. contents:: :local:
+
+Introduction
+============
+
 The goal of refcount_t API is to provide a minimal API for implementing
 an object's reference counters. While a generic architecture-independent
 implementation from lib/refcount.c uses atomic operations underneath,
-there are a number of differences between some of the refcount_*() and
-atomic_*() functions with regards to the memory ordering guarantees.
+there are a number of differences between some of the ``refcount_*()`` and
+``atomic_*()`` functions with regards to the memory ordering guarantees.
 This document outlines the differences and provides respective examples
 in order to help maintainers validate their code against the change in
 these memory ordering guarantees.
@@ -17,17 +22,17 @@ memory ordering in general and for atomic operations specifically.
 Relevant types of memory ordering
 =================================
 
-**Note**: the following section only covers some of the memory
-ordering types that are relevant for the atomics and reference
-counters and used through this document. For a much broader picture
-please consult memory-barriers.txt document.
+.. note:: The following section only covers some of the memory
+   ordering types that are relevant for the atomics and reference
+   counters and used through this document. For a much broader picture
+   please consult memory-barriers.txt document.
 
 In the absence of any memory ordering guarantees (i.e. fully unordered)
 atomics & refcounters only provide atomicity and
 program order (po) relation (on the same CPU). It guarantees that
-each atomic_*() and refcount_*() operation is atomic and instructions
+each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions
 are executed in program order on a single CPU.
-This is implemented using READ_ONCE()/WRITE_ONCE() and
+This is implemented using :c:func:`READ_ONCE`/:c:func:`WRITE_ONCE` and
 compare-and-swap primitives.
 
 A strong (full) memory ordering guarantees that all prior loads and
@@ -36,14 +41,15 @@ before any po-later instruction is executed on the same CPU.
 It also guarantees that all po-earlier stores on the same CPU
 and all propagated stores from other CPUs must propagate to all
 other CPUs before any po-later instruction is executed on the original
-CPU (A-cumulative property). This is implemented using smp_mb().
+CPU (A-cumulative property). This is implemented using :c:func:`smp_mb`.
 
 A RELEASE memory ordering guarantees that all prior loads and
 stores (all po-earlier instructions) on the same CPU are completed
 before the operation. It also guarantees that all po-earlier
 stores on the same CPU and all propagated stores from other CPUs
 must propagate to all other CPUs before the release operation
-(A-cumulative property). This is implemented using smp_store_release().
+(A-cumulative property). This is implemented using
+:c:func:`smp_store_release`.
 
 A control dependency (on success) for refcounters guarantees that
 if a reference for an object was successfully obtained (reference
@@ -61,59 +67,70 @@ case 1) - non-"Read/Modify/Write" (RMW) ops
 -------------------------------------------
 
 Function changes:
-                atomic_set() --> refcount_set()
-                atomic_read() --> refcount_read()
+
+ * :c:func:`atomic_set` --> :c:func:`refcount_set`
+ * :c:func:`atomic_read` --> :c:func:`refcount_read`
 
 Memory ordering guarantee changes:
-                none (both fully unordered)
+
+ * none (both fully unordered)
+
 
 case 2) - increment-based ops that return no value
 --------------------------------------------------
 
 Function changes:
-                atomic_inc() --> refcount_inc()
-                atomic_add() --> refcount_add()
+
+ * :c:func:`atomic_inc` --> :c:func:`refcount_inc`
+ * :c:func:`atomic_add` --> :c:func:`refcount_add`
 
 Memory ordering guarantee changes:
-                none (both fully unordered)
 
+ * none (both fully unordered)
 
 case 3) - decrement-based RMW ops that return no value
 ------------------------------------------------------
+
 Function changes:
-                atomic_dec() --> refcount_dec()
+
+ * :c:func:`atomic_dec` --> :c:func:`refcount_dec`
 
 Memory ordering guarantee changes:
-                fully unordered --> RELEASE ordering
+
+ * fully unordered --> RELEASE ordering
 
 
 case 4) - increment-based RMW ops that return a value
 -----------------------------------------------------
 
 Function changes:
-                atomic_inc_not_zero() --> refcount_inc_not_zero()
-                no atomic counterpart --> refcount_add_not_zero()
+
+ * :c:func:`atomic_inc_not_zero` --> :c:func:`refcount_inc_not_zero`
+ * no atomic counterpart --> :c:func:`refcount_add_not_zero`
 
 Memory ordering guarantees changes:
-                fully ordered --> control dependency on success for stores
 
-*Note*: we really assume here that necessary ordering is provided as a result
-of obtaining pointer to the object!
+ * fully ordered --> control dependency on success for stores
+
+.. note:: We really assume here that necessary ordering is provided as a
+   result of obtaining pointer to the object!
 
 
 case 5) - decrement-based RMW ops that return a value
 -----------------------------------------------------
 
 Function changes:
-                atomic_dec_and_test() --> refcount_dec_and_test()
-                atomic_sub_and_test() --> refcount_sub_and_test()
-                no atomic counterpart --> refcount_dec_if_one()
-                atomic_add_unless(&var, -1, 1) --> refcount_dec_not_one(&var)
+
+ * :c:func:`atomic_dec_and_test` --> :c:func:`refcount_dec_and_test`
+ * :c:func:`atomic_sub_and_test` --> :c:func:`refcount_sub_and_test`
+ * no atomic counterpart --> :c:func:`refcount_dec_if_one`
+ * ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)``
 
 Memory ordering guarantees changes:
-                fully ordered --> RELEASE ordering + control dependency
 
-Note: atomic_add_unless() only provides full order on success.
+ * fully ordered --> RELEASE ordering + control dependency
+
+.. note:: :c:func:`atomic_add_unless` only provides full order on success.
 
 
 case 6) - lock-based RMW
@@ -121,9 +138,10 @@ case 6) - lock-based RMW
 
 Function changes:
 
-                atomic_dec_and_lock() --> refcount_dec_and_lock()
-                atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock()
+ * :c:func:`atomic_dec_and_lock` --> :c:func:`refcount_dec_and_lock`
+ * :c:func:`atomic_dec_and_mutex_lock` --> :c:func:`refcount_dec_and_mutex_lock`
 
 Memory ordering guarantees changes:
-                fully ordered --> RELEASE ordering + control dependency +
-                                  hold spin_lock() on success
+
+ * fully ordered --> RELEASE ordering + control dependency + hold
+   :c:func:`spin_lock` on success
diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
index 73fa7d42bbba..826e85d50a16 100644
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -13,12 +13,6 @@ Driver device table
 .. kernel-doc:: include/linux/mod_devicetable.h
    :internal:
 
-Atomic and pointer manipulation
--------------------------------
-
-.. kernel-doc:: arch/x86/include/asm/atomic.h
-   :internal:
-
 Delaying, scheduling, and timer routines
 ----------------------------------------
 
@@ -85,6 +79,21 @@ Internal Functions
 .. kernel-doc:: kernel/kthread.c
    :export:
 
+Reference counting
+------------------
+
+.. kernel-doc:: include/linux/refcount.h
+   :internal:
+
+.. kernel-doc:: lib/refcount.c
+   :export:
+
+Atomics
+-------
+
+.. kernel-doc:: arch/x86/include/asm/atomic.h
+   :internal:
+
 Kernel objects manipulation
 ---------------------------
 
diff --git a/include/linux/refcount.h b/include/linux/refcount.h
index e8286585e149..4193c41e383a 100644
--- a/include/linux/refcount.h
+++ b/include/linux/refcount.h
@@ -8,7 +8,7 @@
 #include <linux/kernel.h>
 
 /**
- * refcount_t - variant of atomic_t specialized for reference counts
+ * struct refcount_t - variant of atomic_t specialized for reference counts
  * @refs: atomic_t counter field
  *
  * The counter saturates at UINT_MAX and will not move once
-- 
2.7.4


-- 
Kees Cook
Pixel Security

Powered by blists - more mailing lists