[PATCH 0/3] docs: a few improvements for atomic_ops.rst

[PATCH 0/3] docs: a few improvements for atomic_ops.rst

[Jonathan Neuschäfer]

Hi,

this is a short series of unrelated fixes that make the atomic
operations documentation look and read a bit better.

Jonathan Neuschäfer (3):
  docs: atomic_ops: Remove colons where they don't make sense
  docs: atomic_ops: Move two paragraphs into the warning block above
  docs: atomic_ops: Steer readers towards using refcount_t for reference
    counts

 Documentation/core-api/atomic_ops.rst         | 24 ++++++++++++-------
 Documentation/core-api/refcount-vs-atomic.rst |  2 ++
 2 files changed, 17 insertions(+), 9 deletions(-)

--
2.20.1

[PATCH 1/3] docs: atomic_ops: Remove colons where they don't make sense

[Jonathan Neuschäfer]

There are a few cases on atomic_ops.rst, where a end-of-line colon
before a code block seems semantically wrong, because the code block is
not related to the sentence before it.

End those lines with `. ::` instead, which is rendered as a period but
still formats the next line/block as a code block.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
---
 Documentation/core-api/atomic_ops.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/core-api/atomic_ops.rst b/Documentation/core-api/atomic_ops.rst
index 724583453e1f..650b9693469a 100644
--- a/Documentation/core-api/atomic_ops.rst
+++ b/Documentation/core-api/atomic_ops.rst
@@ -242,13 +242,13 @@ given atomic counter.  They return a boolean indicating whether the
 resulting counter value was zero or not.

 Again, these primitives provide explicit memory barrier semantics around
-the atomic operation::
+the atomic operation. ::

 	int atomic_sub_and_test(int i, atomic_t *v);

 This is identical to atomic_dec_and_test() except that an explicit
 decrement is given instead of the implicit "1".  This primitive must
-provide explicit memory barrier semantics around the operation::
+provide explicit memory barrier semantics around the operation. ::

 	int atomic_add_negative(int i, atomic_t *v);

--
2.20.1

[PATCH 2/3] docs: atomic_ops: Move two paragraphs into the warning block above

[Jonathan Neuschäfer]

These two paragraphs seem to be semantically part of the warning text,
so let's adjust the formatting accordingly.

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
---
 Documentation/core-api/atomic_ops.rst | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/core-api/atomic_ops.rst b/Documentation/core-api/atomic_ops.rst
index 650b9693469a..73033fc954ad 100644
--- a/Documentation/core-api/atomic_ops.rst
+++ b/Documentation/core-api/atomic_ops.rst
@@ -473,14 +473,14 @@ operation.
         above to return "long" and just returning something like "old_val &
         mask" because that will not work.

-For one thing, this return value gets truncated to int in many code
-paths using these interfaces, so on 64-bit if the bit is set in the
-upper 32-bits then testers will never see that.
-
-One great example of where this problem crops up are the thread_info
-flag operations.  Routines such as test_and_set_ti_thread_flag() chop
-the return value into an int.  There are other places where things
-like this occur as well.
+        For one thing, this return value gets truncated to int in many code
+        paths using these interfaces, so on 64-bit if the bit is set in the
+        upper 32-bits then testers will never see that.
+
+        One great example of where this problem crops up are the thread_info
+        flag operations.  Routines such as test_and_set_ti_thread_flag() chop
+        the return value into an int.  There are other places where things
+        like this occur as well.

 These routines, like the atomic_t counter operations returning values,
 must provide explicit memory barrier semantics around their execution.
--
2.20.1

[PATCH 3/3] docs: atomic_ops: Steer readers towards using refcount_t for reference counts

[Jonathan Neuschäfer]

Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
---
 Documentation/core-api/atomic_ops.rst         | 6 ++++++
 Documentation/core-api/refcount-vs-atomic.rst | 2 ++
 2 files changed, 8 insertions(+)

diff --git a/Documentation/core-api/atomic_ops.rst b/Documentation/core-api/atomic_ops.rst
index 73033fc954ad..37a0ffe1a9f1 100644
--- a/Documentation/core-api/atomic_ops.rst
+++ b/Documentation/core-api/atomic_ops.rst
@@ -392,6 +392,12 @@ be guaranteed that no other entity can be accessing the object::
 	memory barriers in kfree_skb() that exposed the atomic_t memory barrier
 	requirements quite clearly.

+.. note::
+
+        More recently, reference counts are implement using the
+        :ref:`refcount_t <refcount_t_vs_atomic_t>` type, which works like
+        atomic_t but protects against wraparound.
+
 Given the above scheme, it must be the case that the obj->active
 update done by the obj list deletion be visible to other processors
 before the atomic counter decrement is performed.
diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
index 79a009ce11df..d979ff5166ae 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -1,3 +1,5 @@
+.. _refcount_t_vs_atomic_t:
+
 ===================================
 refcount_t API compared to atomic_t
 ===================================
--
2.20.1

Re: [PATCH 3/3] docs: atomic_ops: Steer readers towards using refcount_t for reference counts

[Randy Dunlap]

On 3/8/20 1:00 PM, Jonathan Neuschäfer wrote:
> Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
> ---
>  Documentation/core-api/atomic_ops.rst         | 6 ++++++
>  Documentation/core-api/refcount-vs-atomic.rst | 2 ++
>  2 files changed, 8 insertions(+)
> 
> diff --git a/Documentation/core-api/atomic_ops.rst b/Documentation/core-api/atomic_ops.rst
> index 73033fc954ad..37a0ffe1a9f1 100644
> --- a/Documentation/core-api/atomic_ops.rst
> +++ b/Documentation/core-api/atomic_ops.rst
> @@ -392,6 +392,12 @@ be guaranteed that no other entity can be accessing the object::
>  	memory barriers in kfree_skb() that exposed the atomic_t memory barrier
>  	requirements quite clearly.
> 
> +.. note::
> +
> +        More recently, reference counts are implement using the

                                               implemented

> +        :ref:`refcount_t <refcount_t_vs_atomic_t>` type, which works like
> +        atomic_t but protects against wraparound.
> +
>  Given the above scheme, it must be the case that the obj->active
>  update done by the obj list deletion be visible to other processors
>  before the atomic counter decrement is performed.


-- 
~Randy

Re: [PATCH 3/3] docs: atomic_ops: Steer readers towards using refcount_t for reference counts

[Jonathan Neuschäfer]

[-- Attachment #1: Type: text/plain, Size: 312 bytes --]

On Sun, Mar 08, 2020 at 02:07:46PM -0700, Randy Dunlap wrote:
> On 3/8/20 1:00 PM, Jonathan Neuschäfer wrote:
[...]
> > +        More recently, reference counts are implement using the
> 
>                                                implemented

Indeed, good catch.

Thanks,
Jonathan Neuschäfer

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 0/3] docs: a few improvements for atomic_ops.rst

[Peter Zijlstra]

On Sun, Mar 08, 2020 at 08:56:15PM +0100, Jonathan Neuschäfer wrote:
> Hi,
> 
> this is a short series of unrelated fixes that make the atomic
> operations documentation look and read a bit better.
> 
> Jonathan Neuschäfer (3):
>   docs: atomic_ops: Remove colons where they don't make sense
>   docs: atomic_ops: Move two paragraphs into the warning block above
>   docs: atomic_ops: Steer readers towards using refcount_t for reference
>     counts
> 
>  Documentation/core-api/atomic_ops.rst         | 24 ++++++++++++-------

FWIW, I consider this a dead document. I've written
Documentation/atomic_t.txt and Documentation/atomic_bitops.txt as a
replacement. If there is anything in atomic_ops you feel is missing from
those two, please tell as I'm planing to delete atomic_ops soon.

Re: [PATCH 0/3] docs: a few improvements for atomic_ops.rst

[Will Deacon]

On Mon, Mar 09, 2020 at 10:06:50AM +0100, Peter Zijlstra wrote:
> On Sun, Mar 08, 2020 at 08:56:15PM +0100, Jonathan Neuschäfer wrote:
> > Hi,
> > 
> > this is a short series of unrelated fixes that make the atomic
> > operations documentation look and read a bit better.
> > 
> > Jonathan Neuschäfer (3):
> >   docs: atomic_ops: Remove colons where they don't make sense
> >   docs: atomic_ops: Move two paragraphs into the warning block above
> >   docs: atomic_ops: Steer readers towards using refcount_t for reference
> >     counts
> > 
> >  Documentation/core-api/atomic_ops.rst         | 24 ++++++++++++-------
> 
> FWIW, I consider this a dead document. I've written
> Documentation/atomic_t.txt and Documentation/atomic_bitops.txt as a
> replacement. If there is anything in atomic_ops you feel is missing from
> those two, please tell as I'm planing to delete atomic_ops soon.

For the deletion:

Acked-by: Will Deacon <will@kernel.org>

Will