[PATCH -perfbook 0/4] memorder: Add index markers

[PATCH -perfbook 0/4] memorder: Add index markers

[Akira Yokosawa]

Hi Paul,

Somehow, "address dependency", "control dependency", and "data
dependency" are missing in Index.

Let's add them.

Having them in glossaries might be a good idea.

Patch 4/4 fixes an issue in flat form index where the words in
the text are used as index entries marked with \IXalth{}{}{}.

        Thanks, Akira
--
Akira Yokosawa (4):
  memorder: Add index markers for 'address/control/data dependency',
    take 1
  memorder: Add index markers for 'address/control/data dependency',
    take 2
  memorder: Add index marker for smp_read_barrier_depends() as classic
    API
  Fix definition of \indexh for flat index pages

 indexsee.tex          |  3 +++
 memorder/memorder.tex | 19 +++++++++++--------
 perfbook-lt.tex       |  2 +-
 3 files changed, 15 insertions(+), 9 deletions(-)


base-commit: 1bb7254318e196c808d3620c230707d989eb536e
-- 
2.25.1

[PATCH -perfbook 1/4] memorder: Add index markers for 'address/control/data dependency', take 1

[Akira Yokosawa]

Add index markers of bold face for "address dependency", "control
dependency", and "data dependency" at their corresponding sections
in memorder.

(hierarchical form)

    - Dependency
          address
          control
          data

  with additional "see xxxx" entries as follows:

    - Address dependency, see Dependency, address
    - Control dependency, see Dependency, control
    - Data dependency, see Dependency, data

(flat form)

    - Address dependency
    - Control dependency
    - Data dependency

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 indexsee.tex          | 3 +++
 memorder/memorder.tex | 6 +++---
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/indexsee.tex b/indexsee.tex
index bd82fa1debfd..a77e9d642824 100644
--- a/indexsee.tex
+++ b/indexsee.tex
@@ -1,3 +1,4 @@
+\index{Address dependency|see{Dependency, address}}
 \index{Anti-Heisenbug|see{Heisenbug, anti-}}
 \index{Associativity|see{Cache associativity}}
 \index{Associativity miss|see{Cache miss, associativity}}
@@ -8,6 +9,8 @@
 \index{Capacity miss|see{Cache miss, capacity}}
 \index{Code locking|see{Locking, code}}
 \index{Communication miss|see{Cache miss, communication}}
+\index{Control dependency|see{Dependency, control}}
+\index{Data dependency|see{Dependency, data}}
 \index{Data locking|see{Locking, data}}
 \index{Direct-mapped cache|see{Cache, direct-mapped}}
 \index{Exclusive lock|see{Lock, exclusive}}
diff --git a/memorder/memorder.tex b/memorder/memorder.tex
index 86bb8f41b5f8..9610618b41f4 100644
--- a/memorder/memorder.tex
+++ b/memorder/memorder.tex
@@ -1815,7 +1815,7 @@ thus preventing the \co{exists} clause from triggering.
 \subsection{Address Dependencies}
 \label{sec:memorder:Address Dependencies}
 
-An \emph{address dependency} occurs when the value returned by a load
+An \emph{\IXBh{address}{dependency}} occurs when the value returned by a load
 instruction is used to compute the address used by a later memory-reference
 instruction.
 This means that the exact same sequence of instructions used to traverse
@@ -2028,7 +2028,7 @@ be fragile and easily broken by compiler optimizations, as discussed in
 \subsection{Data Dependencies}
 \label{sec:memorder:Data Dependencies}
 
-A \emph{data dependency} occurs when the value returned by a load
+A \emph{\IXBh{data}{dependency}} occurs when the value returned by a load
 instruction is used to compute the data stored by a later store
 instruction.
 Note well the ``data'' above:
@@ -2104,7 +2104,7 @@ compiler from breaking them.
 \subsection{Control Dependencies}
 \label{sec:memorder:Control Dependencies}
 
-A \emph{control dependency} occurs when the value returned by a load
+A \emph{\IXBh{control}{dependency}} occurs when the value returned by a load
 instruction is tested to determine whether or not a later store instruction
 is executed.
 In other words, a simple conditional branch or conditional-move
-- 
2.25.1

[PATCH -perfbook 2/4] memorder: Add index markers for 'address/control/data dependency', take 2

[Akira Yokosawa]

Add a few more index markers.

Note that the macro \IXpl{} and its friends don't work for the
plural form of "dependencies".

\IXalth{}{}{} is used instead.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 memorder/memorder.tex | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/memorder/memorder.tex b/memorder/memorder.tex
index 9610618b41f4..9af41194f1de 100644
--- a/memorder/memorder.tex
+++ b/memorder/memorder.tex
@@ -3411,7 +3411,8 @@ In contrast, the penalty for failing to use them when needed can be quite high.
 \label{sec:memorder:Address- and Data-Dependency Difficulties}
 \OriginallyPublished{sec:memorder:Address- and Data-Dependency Difficulties}{Address- and Data-Dependency Difficulties}{the Linux kernel}{PaulEMcKenney2014rcu-dereference}
 
-The low overheads of the address and data dependencies discussed in
+The low overheads of the \IXalth{address}{address}{dependency}
+and \IXalth{data dependencies}{data}{dependency} discussed in
 \cref{sec:memorder:Address Dependencies,%
 sec:memorder:Data Dependencies},
 respectively, makes their use extremely attractive.
@@ -3770,7 +3771,7 @@ compiler-generated assembly code.
 \subsection{Control-Dependency Calamities}
 \label{sec:memorder:Control-Dependency Calamities}
 
-The control dependencies described in
+The \IXalth{control dependencies}{control}{dependency} described in
 \cref{sec:memorder:Control Dependencies}
 are attractive due to their low overhead, but are also especially
 tricky because current compilers do not understand them and can easily
@@ -5403,7 +5404,8 @@ One could place an \co{smp_rmb()} primitive
 between the pointer fetch and dereference in order to force Alpha
 to order the pointer fetch with the later dependent load.
 However, this imposes unneeded overhead on systems (such as \ARM,
-Itanium, PPC, and SPARC) that respect address dependencies on the read side.
+Itanium, PPC, and SPARC) that respect
+\IXalth{address dependencies}{address}{dependency} on the read side.
 A \co{smp_read_barrier_depends()} primitive was therefore added to the
 Linux kernel to eliminate overhead on these systems, but was removed
 in v5.9 of the Linux kernel in favor of augmenting Alpha's definition
@@ -5550,7 +5552,8 @@ similar to that of \Power{}'s cumulativity, both of which are
 stronger than \IXacr{lkmm}'s cumulativity described in
 \cref{sec:memorder:Cumulativity}.
 
-\ARM\ also implements control dependencies, so that if a conditional
+\ARM\ also implements \IXalth{control dependencies}{control}{dependency},
+so that if a conditional
 branch depends on a load, then any store executed after that conditional
 branch will be ordered after the load.
 However, loads following the conditional branch will \emph{not}
-- 
2.25.1

[PATCH -perfbook 3/4] memorder: Add index marker for smp_read_barrier_depends() as classic API

[Akira Yokosawa]

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 memorder/memorder.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/memorder/memorder.tex b/memorder/memorder.tex
index 9af41194f1de..3d2881df6b35 100644
--- a/memorder/memorder.tex
+++ b/memorder/memorder.tex
@@ -5293,7 +5293,7 @@ influence on concurrency APIs, including within the Linux kernel.
 The need for core Linux-kernel code to accommodate Alpha ended
 with version v4.15 of the Linux kernel, and all traces of this
 accommodation were removed in v5.9 with the removal of the
-\co{smp_read_barrier_depends()} and \co{read_barrier_depends()} APIs.
+\apikh{smp_read_barrier_depends()} and \co{read_barrier_depends()} APIs.
 This section is nevertheless retained in the Third Edition
 because here in early 2023 there are still a few Linux kernel hackers
 still working on pre-v4.15 versions of the Linux kernel.
-- 
2.25.1

[PATCH -perfbook 4/4] Fix definition of \indexh for flat index pages

[Akira Yokosawa]

Current definition results in random original terms appearing
in the flat index.  Fix this by using "#3 #2" (second-level term) +
(first-level term) for flat index.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 perfbook-lt.tex | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/perfbook-lt.tex b/perfbook-lt.tex
index 3adf512effcb..cddff24f1d42 100644
--- a/perfbook-lt.tex
+++ b/perfbook-lt.tex
@@ -217,7 +217,7 @@
 \newcommand{\indexhr}[3]{\indexhraw{#2}{#3}}
 \newcommand{\indexhmr}[3]{\ucindexhm{#2}{#3}}
 }{
-\newcommand{\indexh}[3]{\ucindex{#1}}
+\newcommand{\indexh}[3]{\ucindex{#3 #2}}
 \newcommand{\indexhr}[3]{\index{#1}}
 \newcommand{\indexhmr}[3]{\index{#1}}
 }
-- 
2.25.1

Re: [PATCH -perfbook 2/4] memorder: Add index markers for 'address/control/data dependency', take 2

[Paul E. McKenney]

On Fri, Sep 22, 2023 at 10:55:44PM +0900, Akira Yokosawa wrote:
> Add a few more index markers.
> 
> Note that the macro \IXpl{} and its friends don't work for the
> plural form of "dependencies".
> 
> \IXalth{}{}{} is used instead.
> 
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
>  memorder/memorder.tex | 11 +++++++----
>  1 file changed, 7 insertions(+), 4 deletions(-)
> 
> diff --git a/memorder/memorder.tex b/memorder/memorder.tex
> index 9610618b41f4..9af41194f1de 100644
> --- a/memorder/memorder.tex
> +++ b/memorder/memorder.tex
> @@ -3411,7 +3411,8 @@ In contrast, the penalty for failing to use them when needed can be quite high.
>  \label{sec:memorder:Address- and Data-Dependency Difficulties}
>  \OriginallyPublished{sec:memorder:Address- and Data-Dependency Difficulties}{Address- and Data-Dependency Difficulties}{the Linux kernel}{PaulEMcKenney2014rcu-dereference}
>  
> -The low overheads of the address and data dependencies discussed in
> +The low overheads of the \IXalth{address}{address}{dependency}

This looks strange given the different parameters to the \IXalth above
and the \IXalth below, but it gets the right thing to the right place
in the index, so I queued and pushed all four.

Thank you!!!  And yes, I am now generating a set of glossary entries.  ;-)

							Thanx, Paul

> +and \IXalth{data dependencies}{data}{dependency} discussed in
>  \cref{sec:memorder:Address Dependencies,%
>  sec:memorder:Data Dependencies},
>  respectively, makes their use extremely attractive.
> @@ -3770,7 +3771,7 @@ compiler-generated assembly code.
>  \subsection{Control-Dependency Calamities}
>  \label{sec:memorder:Control-Dependency Calamities}
>  
> -The control dependencies described in
> +The \IXalth{control dependencies}{control}{dependency} described in
>  \cref{sec:memorder:Control Dependencies}
>  are attractive due to their low overhead, but are also especially
>  tricky because current compilers do not understand them and can easily
> @@ -5403,7 +5404,8 @@ One could place an \co{smp_rmb()} primitive
>  between the pointer fetch and dereference in order to force Alpha
>  to order the pointer fetch with the later dependent load.
>  However, this imposes unneeded overhead on systems (such as \ARM,
> -Itanium, PPC, and SPARC) that respect address dependencies on the read side.
> +Itanium, PPC, and SPARC) that respect
> +\IXalth{address dependencies}{address}{dependency} on the read side.
>  A \co{smp_read_barrier_depends()} primitive was therefore added to the
>  Linux kernel to eliminate overhead on these systems, but was removed
>  in v5.9 of the Linux kernel in favor of augmenting Alpha's definition
> @@ -5550,7 +5552,8 @@ similar to that of \Power{}'s cumulativity, both of which are
>  stronger than \IXacr{lkmm}'s cumulativity described in
>  \cref{sec:memorder:Cumulativity}.
>  
> -\ARM\ also implements control dependencies, so that if a conditional
> +\ARM\ also implements \IXalth{control dependencies}{control}{dependency},
> +so that if a conditional
>  branch depends on a load, then any store executed after that conditional
>  branch will be ordered after the load.
>  However, loads following the conditional branch will \emph{not}
> -- 
> 2.25.1
> 
> 

Re: [PATCH -perfbook 2/4] memorder: Add index markers for 'address/control/data dependency', take 2

[Akira Yokosawa]

Hi,

On 2023/09/23 17:23, Paul E. McKenney wrote:
> On Fri, Sep 22, 2023 at 10:55:44PM +0900, Akira Yokosawa wrote:
[...]
>>  
>> -The low overheads of the address and data dependencies discussed in
>> +The low overheads of the \IXalth{address}{address}{dependency}
> 
> This looks strange given the different parameters to the \IXalth above
> and the \IXalth below, but it gets the right thing to the right place
> in the index, so I queued and pushed all four.
> 
[...]
>> +and \IXalth{data dependencies}{data}{dependency} discussed in

Let me explain what's happening here.

Original sentence looked like this:

    The low overheads of the address and data dependencies discussed in

Here, if "address dependencies" were there, I could have said:

    \IXalth{address dependencies}{address}{dependency}

Instead, I put an index marker of "Dependency, address" on the lonely
"address", therefore it became:

    \IXalth{address}{address}{dependency}

\IXalth{}{}{} prints any string in #1 with an index marker of
"#3, #2" put on it.

Macros of \IX*alt* are powerful and can do whatever you'd like.

> Thank you!!!  And yes, I am now generating a set of glossary entries.  ;-)

Thank you.  I like those cautionary remarks.

        Thanks, Akira

> 
> 							Thanx, Paul

Re: [PATCH -perfbook 2/4] memorder: Add index markers for 'address/control/data dependency', take 2

[Paul E. McKenney]

On Tue, Sep 26, 2023 at 07:04:12PM +0900, Akira Yokosawa wrote:
> Hi,
> 
> On 2023/09/23 17:23, Paul E. McKenney wrote:
> > On Fri, Sep 22, 2023 at 10:55:44PM +0900, Akira Yokosawa wrote:
> [...]
> >>  
> >> -The low overheads of the address and data dependencies discussed in
> >> +The low overheads of the \IXalth{address}{address}{dependency}
> > 
> > This looks strange given the different parameters to the \IXalth above
> > and the \IXalth below, but it gets the right thing to the right place
> > in the index, so I queued and pushed all four.
> > 
> [...]
> >> +and \IXalth{data dependencies}{data}{dependency} discussed in
> 
> Let me explain what's happening here.
> 
> Original sentence looked like this:
> 
>     The low overheads of the address and data dependencies discussed in
> 
> Here, if "address dependencies" were there, I could have said:
> 
>     \IXalth{address dependencies}{address}{dependency}
> 
> Instead, I put an index marker of "Dependency, address" on the lonely
> "address", therefore it became:
> 
>     \IXalth{address}{address}{dependency}
> 
> \IXalth{}{}{} prints any string in #1 with an index marker of
> "#3, #2" put on it.
> 
> Macros of \IX*alt* are powerful and can do whatever you'd like.

Got it, thank you for the explanation!  And indeed they are powerful!

> > Thank you!!!  And yes, I am now generating a set of glossary entries.  ;-)
> 
> Thank you.  I like those cautionary remarks.

Glad you like them!

							Thanx, Paul