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;
Date:   Tue, 21 Jun 2022 11:53:40 -0700
From:   "Paul E. McKenney" <paulmck@kernel.org>
To:     Akira Yokosawa <akiyks@gmail.com>
Cc:     Alan Stern <stern@rowland.harvard.edu>,
        Will Deacon <will@kernel.org>,
        "Michael S. Tsirkin" <mst@redhat.com>,
        Peter Zijlstra <peterz@infradead.org>,
        Boqun Feng <boqun.feng@gmail.com>,
        Andrea Parri <parri.andrea@gmail.com>,
        Nicholas Piggin <npiggin@gmail.com>,
        David Howells <dhowells@redhat.com>,
        Daniel Lustig <dlustig@nvidia.com>,
        Jonathan Corbet <corbet@lwn.net>, linux-kernel@vger.kernel.org,
        linux-doc@vger.kernel.org
Subject: Re: [PATCH RESEND v1 0/2] docs/memory-barriers.txt: Fix confusing
 name of 'data dependency barrier'
Message-ID: <20220621185340.GK1790663@paulmck-ThinkPad-P17-Gen-1>
Reply-To: paulmck@kernel.org
References: <a84435e4-5342-f886-4388-e4c5909298a7@gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <a84435e4-5342-f886-4388-e4c5909298a7@gmail.com>
Precedence: bulk

On Mon, Jun 20, 2022 at 05:16:04PM +0900, Akira Yokosawa wrote:
> I used Paul's old email address in RFC and v1.  My bad.
> Sorry for making noise to other recipients.
> 
> Paul, please see RFC [1] for the discussion so far.
> There was no response to v1.

Thank you for resending, Akira!  I have queued it, and also support
the general consensus for creating a "historical" section.

							Thanx, Paul

> -----
> 
> Hi all,
> 
> This is a revised patch set of RFC [1].
> 
> Discussion so far is about possible follow-up improvements,
> so I hereby submit this set as a "v1".
> 
> Changes since RFC [1]:
> 
>   - Rename title of Patch 1/2.
>   - Remove note on the rename of section "DATA DEPENDENCY BARRIER".
>     Rational in the changelog should suffice.
>   - Wordsmith by self review.
>   - Add Patch 2/2 (fixup of long lines).
> 
> [1]: https://lore.kernel.org/linux-doc/cc2c7885-ac75-24f3-e18a-e77f97c91b4c@gmail.com/ # RFC
> 
> For your convenience, diff of "v1 1/2" vs RFC is appended below.
> 
> Following is the explanation of background in RFC (with typo fixes):
> -------------------------------------------------------------------
> This is a response to Michael's report back in last November [2].
> 
> [2]: "data dependency naming inconsistency":
>      https://lore.kernel.org/r/20211011064233-mutt-send-email-mst@kernel.org/
> 
> In the thread, I suggested removing all the explanations of "data dependency
> barriers", which Paul thought was reasonable.
> 
> However, such removal would require involved rewrites in the infamously
> hard-to-grasp document, which is beyond my capability.
> I have become more inclined to just substitute "data dependency barrier"
> with "address-dependency barrier" considering that READ_ONCE() still has
> an implicit address-dependency barrier.
> 
> This patch set is the result of such an attempt.
> 
> Note: I made a mistake in the thread above. Kernel APIs for explicit data
> dependency barriers were removed in v5.9.
> I was confused the removal with the addition of the barrier to Alpha's
> READ_ONCE() in v4.15.
> 
> diff of "v1 1/2" vs RFC
> ------------------------------------------------------------------
> diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
> index 306afa1f9347..bdbea3cc66a3 100644
> --- a/Documentation/memory-barriers.txt
> +++ b/Documentation/memory-barriers.txt
> @@ -391,8 +391,8 @@ Memory barriers come in four basic varieties:
>       memory system as time progresses.  All stores _before_ a write barrier
>       will occur _before_ all the stores after the write barrier.
>  
> -     [!] Note that write barriers should normally be paired with read- or address-
> -     dependency barriers; see the "SMP barrier pairing" subsection.
> +     [!] Note that write barriers should normally be paired with read or
> +     address-dependency barriers; see the "SMP barrier pairing" subsection.
>  
>  
>   (2) Address-dependency barriers (historical).
> @@ -561,17 +561,14 @@ As of v4.15 of the Linux kernel, an smp_mb() was added to READ_ONCE() for
>  DEC Alpha, which means that about the only people who need to pay attention
>  to this section are those working on DEC Alpha architecture-specific code
>  and those working on READ_ONCE() itself.  For those who need it, and for
> -those who are interested in the history, here is the story of address-
> -dependency barriers.
> +those who are interested in the history, here is the story of
> +address-dependency barriers.
>  
> -[!] The title of this section was renamed from "DATA DEPENDENCY BARRIERS"
> -to prevent developer confusion as "data dependencies" usually refers to
> -load-to-store data dependencies.
> -While address dependencies are observed in both load-to-load and load-to-
> -store relations, address-dependency barriers concern only load-to-load
> -situations.
> +[!] While address dependencies are observed in both load-to-load and
> +load-to-store relations, address-dependency barriers are not necessary
> +for load-to-store situations.
>  
> -The usage requirements of address-dependency barriers are a little subtle, and
> +The requirement of address-dependency barriers is a little subtle, and
>  it's not always obvious that they're needed.  To illustrate, consider the
>  following sequence of events:
>  
> @@ -602,8 +599,8 @@ While this may seem like a failure of coherency or causality maintenance, it
>  isn't, and this behaviour can be observed on certain real CPUs (such as the DEC
>  Alpha).
>  
> -To deal with this, an implicit address-dependency barrier of READ_ONCE()
> -or better must be inserted between the address load and the data load:
> +To deal with this, READ_ONCE() provides an implicit address-dependency
> +barrier since kernel release v4.15:
>  
>  	CPU 1		      CPU 2
>  	===============	      ===============
> @@ -659,11 +656,9 @@ can be used to record rare error conditions and the like, and the CPUs'
>  naturally occurring ordering prevents such records from being lost.
>  
>  
> -Note well that the ordering provided by an address or a data dependency is local to
> +Note well that the ordering provided by an address dependency is local to
>  the CPU containing it.  See the section on "Multicopy atomicity" for
>  more information.
>  
> ---------------------------------------------------------------------
> 
>         Thanks, Akira
> --
> Akira Yokosawa (2):
>   docs/memory-barriers.txt: Fix confusing name of 'data dependency
>     barrier'
>   docs/memory-barriers.txt: Fixup long lines
> 
>  Documentation/memory-barriers.txt | 177 ++++++++++++++++--------------
>  1 file changed, 95 insertions(+), 82 deletions(-)
> 
> 
> base-commit: c09ca10d879bae4a8df842dbe8d6bd8b87830633
> -- 
> 2.25.1
>