2022-06-20 08:50:55

by Akira Yokosawa

[permalink] [raw]
Subject: [PATCH RESEND v1 0/2] docs/memory-barriers.txt: Fix confusing name of 'data dependency barrier'

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.
-----

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/[email protected]/ # 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/[email protected]/

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


2022-06-21 19:10:42

by Paul E. McKenney

[permalink] [raw]
Subject: Re: [PATCH RESEND v1 0/2] docs/memory-barriers.txt: Fix confusing name of 'data dependency barrier'

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/[email protected]/ # 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/[email protected]/
>
> 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
>