[PATCH 0/6] whymb: Convert to 'description' lists

[PATCH 0/6] whymb: Convert to 'description' lists

[Akira Yokosawa]

From e29e397c3eab7359cdd866d5a59a0af56dfd22c4 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Mon, 20 Mar 2017 00:25:49 +0900
Subject: [PATCH 0/6] whymb: Convert to 'description' lists

Hi Paul,

This series converts some of "itemize" and "enumerate" lists in whymb
to "description" lists. In the fairly old commit 433c1ff9f545 ("pdflatex
apparently doesn't like complex item parameters"), "description" lists
were converted to "itemize" lists, but I don't see what went wrong.

Can you try this?

                                       Thanks, Akira
--
Akira Yokosawa (6):
  whymb: Convert to 'description' (part 1)
  whymb: Convert to 'description' (part 2)
  whymb: Convert to 'description' (part 3)
  whymb: Use 'nextline' style for 'description'
  whymb: Convert to 'description' (part 4)
  whymb: Convert to 'description' (part 5)

 appendix/whymb/whymemorybarriers.tex | 113 ++++++++++++++++++-----------------
 1 file changed, 57 insertions(+), 56 deletions(-)

-- 
2.7.4

[PATCH 1/6] whymb: Convert to 'description' (part 1)

[Akira Yokosawa]

From 20275a2adb3c0fcebe7d2a3ac525862c61fe725b Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 19 Mar 2017 23:21:05 +0900
Subject: [PATCH 1/6] whymb: Convert to 'description' (part 1)

These "itemize" lists look better in "decription" lists with
"nextline" style.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/whymb/whymemorybarriers.tex | 44 ++++++++++++++++++------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/appendix/whymb/whymemorybarriers.tex b/appendix/whymb/whymemorybarriers.tex
index 6e96af4..bd87ee7 100644
--- a/appendix/whymb/whymemorybarriers.tex
+++ b/appendix/whymb/whymemorybarriers.tex
@@ -289,11 +289,11 @@ that coordinate the movement of cache lines through the system.
 Many of the transitions described in the previous section require
 communication among the CPUs.
 If the CPUs are on a single shared bus, the following messages suffice:
-\begin{itemize}
-\item	Read:
+\begin{description}[style=nextline]
+\item	[Read:]
 	The ``read'' message contains the physical address of the cache line
 	to be read.
-\item	Read Response:
+\item	[Read Response:]
 	The ``read response'' message contains the data requested by an
 	earlier ``read'' message.
 	This ``read response'' message might be supplied either by
@@ -301,16 +301,16 @@ If the CPUs are on a single shared bus, the following messages suffice:
 	For example, if one of the caches has the desired data in
 	``modified'' state, that cache must supply the ``read response''
 	message.
-\item	Invalidate:
+\item	[Invalidate:]
 	The ``invalidate'' message contains the physical address of the
 	cache line to be invalidated.
 	All other caches must remove the corresponding data from their
 	caches and respond.
-\item	Invalidate Acknowledge:
+\item	[Invalidate Acknowledge:]
 	A CPU receiving an ``invalidate'' message must respond with an
 	``invalidate acknowledge'' message after removing the specified
 	data from its cache.
-\item	Read Invalidate:
+\item	[Read Invalidate:]
 	The ``read invalidate'' message contains the physical address
 	of the cache line to be read, while at the same time directing
 	other caches to remove the data.
@@ -318,13 +318,13 @@ If the CPUs are on a single shared bus, the following messages suffice:
 	as indicated by its name.
 	A ``read invalidate'' message requires both a ``read response''
 	and a set of ``invalidate acknowledge'' messages in reply.
-\item	Writeback:
+\item	[Writeback:]
 	The ``writeback'' message contains both the address and the
 	data to be written back to memory (and perhaps ``snooped''
 	into other CPUs' caches along the way).
 	This message permits caches to eject lines in the ``modified''
 	state as needed to make room for other data.
-\end{itemize}
+\end{description}

 \QuickQuiz{}
 	Where does a writeback message originate from and where does
@@ -428,51 +428,51 @@ shown in Figure~\ref{fig:app:whymb:MESI Cache-Coherency State Diagram}.
 \end{figure}

 The transition arcs in this figure are as follows:
-\begin{itemize}
-\item	Transition (a):
+\begin{description}[style=nextline]
+\item	[Transition (a):]
 	A cache line is written back to memory, but the CPU retains
 	it in its cache and further retains the right to modify it.
 	This transition requires a ``writeback'' message.
-\item	Transition (b):
+\item	[Transition (b):]
 	The CPU writes to the cache line that it already had exclusive
 	access to.
 	This transition does not require any messages to be sent or
 	received.
-\item	Transition (c):
+\item	[Transition (c):]
 	The CPU receives a ``read invalidate'' message for a cache line
 	that it has modified.
 	The CPU must invalidate its local copy, then respond with both a
 	``read response'' and an ``invalidate acknowledge'' message,
 	both sending the data to the requesting CPU and indicating
 	that it no longer has a local copy.
-\item	Transition (d):
+\item	[Transition (d):]
 	The CPU does an atomic read-modify-write operation on a data item
 	that was not present in its cache.
 	It transmits a ``read invalidate'', receiving the data via
 	a ``read response''.
 	The CPU can complete the transition once it has also received a
 	full set of ``invalidate acknowledge'' responses.
-\item	Transition (e):
+\item	[Transition (e):]
 	The CPU does an atomic read-modify-write operation on a data item
 	that was previously read-only in its cache.
 	It must transmit ``invalidate'' messages, and must wait for a
 	full set of ``invalidate acknowledge'' responses before completing
 	the transition.
-\item	Transition (f):
+\item	[Transition (f):]
 	Some other CPU reads the cache line, and it is supplied from
 	this CPU's cache, which retains a read-only copy, possibly also
 	writing it back to memory.
 	This transition is initiated by the reception of a ``read''
 	message, and this CPU responds with a ``read response'' message
 	containing the requested data.
-\item	Transition (g):
+\item	[Transition (g):]
 	Some other CPU reads a data item in this cache line,
 	and it is supplied either from this CPU's cache or from memory.
 	In either case, this CPU retains a read-only copy.
 	This transition is initiated by the reception of a ``read''
 	message, and this CPU responds with a ``read response'' message
 	containing the requested data.
-\item	Transition (h):
+\item	[Transition (h):]
 	This CPU realizes that it will soon need to write to some data
 	item in this cache line, and thus transmits an ``invalidate'' message.
 	The CPU cannot complete the transition until it receives a full
@@ -481,14 +481,14 @@ The transition arcs in this figure are as follows:
 	their caches via ``writeback'' messages (presumably to make room
 	for other cache lines),
 	so that this CPU is the last CPU caching it.
-\item	Transition (i):
+\item	[Transition (i):]
 	Some other CPU does an atomic read-modify-write operation on
 	a data item in a cache line held only in this CPU's cache,
 	so this CPU invalidates it from its cache.
 	This transition is initiated by the reception of a ``read invalidate''
 	message, and this CPU responds with both a ``read response''
 	and an ``invalidate acknowledge'' message.
-\item	Transition (j):
+\item	[Transition (j):]
 	This CPU does a store to a data item in a cache line that was not
 	in its cache, and thus transmits a ``read invalidate'' message.
 	The CPU cannot complete the transition until it receives the
@@ -496,12 +496,12 @@ The transition arcs in this figure are as follows:
 	messages.
 	The cache line will presumably transition to ``modified'' state via
 	transition (b) as soon as the actual store completes.
-\item	Transition (k):
+\item	[Transition (k):]
 	This CPU loads a data item in a cache line that was not
 	in its cache.
 	The CPU transmits a ``read'' message, and completes the
 	transition upon receiving the corresponding ``read response''.
-\item	Transition (l):
+\item	[Transition (l):]
 	Some other CPU does a store to
 	a data item in this cache line, but holds this cache line in read-only
 	state due to its being held in other CPUs' caches (such as the
@@ -509,7 +509,7 @@ The transition arcs in this figure are as follows:
 	This transition is initiated by the reception of an ``invalidate''
 	message, and this CPU responds with
 	an ``invalidate acknowledge'' message.
-\end{itemize}
+\end{description}

 \QuickQuiz{}
 	How does the hardware handle the delayed transitions
-- 
2.7.4

[PATCH 2/6] whymb: Convert to 'description' (part 2)

[Akira Yokosawa]

From 8b81634e0268329ecdcad3ce731a33d9d42e0786 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Mon, 19 Mar 2017 23:25:12 +0900
Subject: [PATCH 2/6] whymb: Convert to 'description' (part 2)

This list is also a good candidate to convert to "description".
As labels are printed in bold, colons at the tail of API names
can be removed. Also replace double quotes after labels with
parentheses for consistency with other lists in the Appendix.
\tco{} is safer than \co{} in labels.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/whymb/whymemorybarriers.tex | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/appendix/whymb/whymemorybarriers.tex b/appendix/whymb/whymemorybarriers.tex
index bd87ee7..49d29ba 100644
--- a/appendix/whymb/whymemorybarriers.tex
+++ b/appendix/whymb/whymemorybarriers.tex
@@ -1656,18 +1656,18 @@ use of memory barriers is required.
 Therefore,
 Linux provides a carefully chosen least-common-denominator
 set of memory-barrier primitives, which are as follows:
-\begin{itemize}
-\item	\co{smp_mb()}: ``memory barrier'' that orders both loads and
+\begin{description}
+\item	[\tco{smp_mb()}] (memory barrier) that orders both loads and
 	stores.
 	This means that loads and stores preceding the memory barrier
 	will be committed to memory before any loads and stores
 	following the memory barrier.
-\item	\co{smp_rmb()}: ``read memory barrier'' that orders only loads.
-\item	\co{smp_wmb()}: ``write memory barrier'' that orders only stores.
-\item	\co{smp_read_barrier_depends()} that forces subsequent operations
+\item	[\tco{smp_rmb()}] (read memory barrier) that orders only loads.
+\item	[\tco{smp_wmb()}] (write memory barrier) that orders only stores.
+\item	[\tco{smp_read_barrier_depends()}] that forces subsequent operations
 	that depend on prior operations to be ordered.
 	This primitive is a no-op on all platforms except Alpha.
-\item	{\tt mmiowb()} that forces ordering on MMIO writes that are guarded
+\item	[\tco{mmiowb()}] that forces ordering on MMIO writes that are guarded
 	by global spinlocks.
 	This primitive is a no-op on all platforms on which the memory
 	barriers in spinlocks already enforce MMIO ordering.
@@ -1675,7 +1675,7 @@ set of memory-barrier primitives, which are as follows:
 	some (but not all) IA64, FRV, MIPS, and SH systems.
 	This primitive is relatively new, so relatively few drivers take
 	advantage of it.
-\end{itemize}
+\end{description}
 The \co{smp_mb()}, \co{smp_rmb()}, and \co{smp_wmb()}
 primitives also force
 the compiler to eschew any optimizations that would have the effect
-- 
2.7.4

[PATCH 3/6] whymb: Convert to 'description' (part 3)

[Akira Yokosawa]

From 80cfeef3af82ce22777ed075206f5015d071095d Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 19 Mar 2017 23:28:44 +0900
Subject: [PATCH 3/6] whymb: Convert to 'description' (part 3)

This list is also a good candidate to convert to "description".
\tco{} is safer than \co{} in labels.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/whymb/whymemorybarriers.tex | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/appendix/whymb/whymemorybarriers.tex b/appendix/whymb/whymemorybarriers.tex
index 49d29ba..90da0df 100644
--- a/appendix/whymb/whymemorybarriers.tex
+++ b/appendix/whymb/whymemorybarriers.tex
@@ -1969,8 +1969,8 @@ Its memory model is similar to that of Power
 (see Section~\ref{sec:app:whymb:POWER / PowerPC}, but ARM uses a
 different set of memory-barrier instructions~\cite{ARMv7A:2010}:

-\begin{enumerate}
-\item	\co{DMB} (data memory barrier) causes the specified type of
+\begin{description}
+\item	[\tco{DMB}] (data memory barrier) causes the specified type of
 	operations to \emph{appear} to have completed before any
 	subsequent operations of the same type.
 	The ``type'' of operations can be all operations or can be
@@ -1979,20 +1979,20 @@ different set of memory-barrier instructions~\cite{ARMv7A:2010}:
 	In addition, ARM allows cache coherence to have one of three
 	scopes: single processor, a subset of the processors
 	(``inner'') and global (``outer'').
-\item	\co{DSB} (data synchronization barrier) causes the specified
+\item	[\tco{DSB}] (data synchronization barrier) causes the specified
 	type of operations to actually complete before any subsequent
 	operations (of any type) are executed.
 	The ``type'' of operations is the same as that of \co{DMB}.
 	The \co{DSB} instruction was called \co{DWB} (drain write buffer
 	or data write barrier, your choice) in early versions of the
 	ARM architecture.
-\item	\co{ISB} (instruction synchronization barrier) flushes the CPU
+\item	[\tco{ISB}] (instruction synchronization barrier) flushes the CPU
 	pipeline, so that all instructions following the \co{ISB}
 	are fetched only after the \co{ISB} completes.
 	For example, if you are writing a self-modifying program
 	(such as a JIT), you should execute an \co{ISB} between
 	generating the code and executing it.
-\end{enumerate}
+\end{description}

 None of these instructions exactly match the semantics of Linux's
 \co{rmb()} primitive, which must therefore be implemented as a full
-- 
2.7.4

[PATCH 4/6] whymb: Use 'nextline' style for 'description'

[Akira Yokosawa]

From 26833e78b20ac0e7ebf5276fc1e45c9875b067c7 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 19 Mar 2017 23:29:37 +0900
Subject: [PATCH 4/6] whymb: Use 'nextline' style for 'description'

This list looks better in "nextline" style.
Also use \tco{} macro in labels and remove escapes of underscore.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/whymb/whymemorybarriers.tex | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/appendix/whymb/whymemorybarriers.tex b/appendix/whymb/whymemorybarriers.tex
index 90da0df..9015a85 100644
--- a/appendix/whymb/whymemorybarriers.tex
+++ b/appendix/whymb/whymemorybarriers.tex
@@ -2092,26 +2092,26 @@ not to hardware considerations, but rather to the use cases provided
 by the Linux kernel and the C++11 standard~\cite{RichardSmith2015N4527}
 in a manner similar to the ARM64 additions:

-\begin{description}
-\item[SYNC]
+\begin{description}[style=nextline]
+\item[\tco{SYNC}]
 	Full barrier for a number of hardware operations in addition
 	to memory references.
-\item[SYNC\_WMB]
+\item[\tco{SYNC_WMB}]
 	Write memory barrier, which can be used to implement the
 	\co{smp_wmb()} primitive in the Linux kernel.
-\item[SYNC\_MB]
+\item[\tco{SYNC_MB}]
 	Full memory barrier, but only for memory operations.
 	This may be used to implement the Linux-kernel \co{smp_mb()}
 	and the C++ \co{atomic_thread_fence(memory_order_seq_cst)}.
-\item[SYNC\_ACQUIRE]
+\item[\tco{SYNC_ACQUIRE}]
 	Acquire memory barrier, which may be used to implement the
 	Linux-kernel \co{smp_load_acquire()} and the C++
 	\co{atomic_load_explicit(..., memory_order_acquire)}.
-\item[SYNC\_RELEASE]
+\item[\tco{SYNC_RELEASE}]
 	Release memory barrier, which may be used to implement the
 	Linux-kernel \co{smp_store_release()} and the C++
 	\co{atomic_store_explicit(..., memory_order_release)}.
-\item[SYNC\_RMB]
+\item[\tco{SYNC_RMB}]
 	Read memory barrier, which can be used to implement the
 	\co{smp_rmb()} primitive in the Linux kernel.
 \end{description}
-- 
2.7.4

[PATCH 5/6] whymb: Convert to 'description' (part 4)

[Akira Yokosawa]

From 101cacb83ff135f713afecd1edefbc8b5df7b8bc Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 19 Mar 2017 23:32:24 +0900
Subject: [PATCH 5/6] whymb: Convert to 'description' (part 4)

This list is not necessarily to be enumerated and suited to
"description". Using \tco{} in labels enables them to be
in bold face. (Note: "\tt" specifies "normal" typewriter text.)

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/whymb/whymemorybarriers.tex | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/appendix/whymb/whymemorybarriers.tex b/appendix/whymb/whymemorybarriers.tex
index 9015a85..d6dd15f 100644
--- a/appendix/whymb/whymemorybarriers.tex
+++ b/appendix/whymb/whymemorybarriers.tex
@@ -2138,11 +2138,11 @@ barrier.
 The POWER and PowerPC\textsuperscript{\textregistered}
 CPU families have a wide variety of memory-barrier
 instructions~\cite{PowerPC94,MichaelLyons05a}:
-\begin{enumerate}
-\item	{\tt sync} causes all preceding operations to {\em appear to have}
+\begin{description}
+\item	[\tco{sync}] causes all preceding operations to {\em appear to have}
 	completed before any subsequent operations are started.
 	This instruction is therefore quite expensive.
-\item	{\tt lwsync} (light-weight sync) orders loads with respect to
+\item	[\tco{lwsync}] (light-weight sync) orders loads with respect to
 	subsequent loads and stores, and also orders stores.
 	However, it does {\em not} order stores with respect to subsequent
 	loads.
@@ -2151,20 +2151,20 @@ instructions~\cite{PowerPC94,MichaelLyons05a}:
 	SPARC TSO.
 	The \co{lwsync} instruction may be used to implement
 	load-acquire and store-release operations.
-\item	{\tt eieio} (enforce in-order execution of I/O, in case you
+\item	[\tco{eieio}] (enforce in-order execution of I/O, in case you
 	were wondering) causes all preceding cacheable stores to appear
 	to have completed before all subsequent stores.
 	However, stores to cacheable memory are ordered separately from
 	stores to non-cacheable memory, which means that {\tt eieio}
 	will not force an MMIO store to precede a spinlock release.
-\item	{\tt isync} forces all preceding instructions to appear to have
+\item	[\tco{isync}] forces all preceding instructions to appear to have
 	completed before any subsequent instructions start execution.
 	This means that the preceding instructions must have progressed
 	far enough that any traps they might generate have either happened
 	or are guaranteed not to happen, and that any side-effects of
 	these instructions (for example, page-table changes) are seen by the
 	subsequent instructions.
-\end{enumerate}
+\end{description}

 Unfortunately, none of these instructions line up exactly with Linux's
 {\tt wmb()} primitive, which requires {\em all} stores to be ordered,
-- 
2.7.4

[PATCH 6/6] whymb: Convert to 'description' (part 5)

[Akira Yokosawa]

From e29e397c3eab7359cdd866d5a59a0af56dfd22c4 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 19 Mar 2017 23:33:50 +0900
Subject: [PATCH 6/6] whymb: Convert to 'description' (part 5)

This list is also a candidate for conversion to "description".
Also adjust conjugation of verbs that follow labels.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/whymb/whymemorybarriers.tex | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/appendix/whymb/whymemorybarriers.tex b/appendix/whymb/whymemorybarriers.tex
index d6dd15f..6c6b28a 100644
--- a/appendix/whymb/whymemorybarriers.tex
+++ b/appendix/whymb/whymemorybarriers.tex
@@ -2221,22 +2221,23 @@ worry about memory barriers.

 SPARC has a very flexible memory-barrier instruction~\cite{SPARC94}
 that permits fine-grained control of ordering:
-\begin{itemize}
-\item	{\tt StoreStore}: order preceding stores before subsequent stores.
+\begin{description}
+\item	[\tco{StoreStore}] orders preceding stores before subsequent stores.
 	(This option is used by the Linux \co{smp_wmb()} primitive.)
-\item	{\tt LoadStore}: order preceding loads before subsequent stores.
-\item	{\tt StoreLoad}: order preceding stores before subsequent loads.
-\item	{\tt LoadLoad}: order preceding loads before subsequent loads.
+\item	[\tco{LoadStore}] orders preceding loads before subsequent stores.
+\item	[\tco{StoreLoad}] orders preceding stores before subsequent loads.
+\item	[\tco{LoadLoad}] orders preceding loads before subsequent loads.
 	(This option is used by the Linux \co{smp_rmb()} primitive.)
-\item	{\tt Sync}: fully complete all preceding operations before starting
+\item	[\tco{Sync}] fully completes all preceding operations before starting
 	any subsequent operations.
-\item	{\tt MemIssue}: complete preceding memory operations before subsequent
+\item	[\tco{MemIssue}] completes preceding memory operations before subsequent
 	memory operations, important for some instances of memory-mapped
 	I/O.
-\item	{\tt Lookaside}: same as MemIssue, but only applies to preceding stores
+\item	[\tco{Lookaside}] does the same as MemIssue,
+	but only applies to preceding stores
 	and subsequent loads, and even then only for stores and loads that
 	access the same memory location.
-\end{itemize}
+\end{description}

 The Linux \co{smp_mb()} primitive uses the first four options together,
 as in
-- 
2.7.4

Re: [PATCH 0/6] whymb: Convert to 'description' lists

[Paul E. McKenney]

On Mon, Mar 20, 2017 at 12:44:12AM +0900, Akira Yokosawa wrote:
> >From e29e397c3eab7359cdd866d5a59a0af56dfd22c4 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@gmail.com>
> Date: Mon, 20 Mar 2017 00:25:49 +0900
> Subject: [PATCH 0/6] whymb: Convert to 'description' lists
> 
> Hi Paul,
> 
> This series converts some of "itemize" and "enumerate" lists in whymb
> to "description" lists. In the fairly old commit 433c1ff9f545 ("pdflatex
> apparently doesn't like complex item parameters"), "description" lists
> were converted to "itemize" lists, but I don't see what went wrong.
> 
> Can you try this?

Looks fine to me, queued and pushed.  I guess we should expect some
improvement in the tools over the past five years.  ;-)

							Thanx, Paul

>                                        Thanks, Akira
> --
> Akira Yokosawa (6):
>   whymb: Convert to 'description' (part 1)
>   whymb: Convert to 'description' (part 2)
>   whymb: Convert to 'description' (part 3)
>   whymb: Use 'nextline' style for 'description'
>   whymb: Convert to 'description' (part 4)
>   whymb: Convert to 'description' (part 5)
> 
>  appendix/whymb/whymemorybarriers.tex | 113 ++++++++++++++++++-----------------
>  1 file changed, 57 insertions(+), 56 deletions(-)
> 
> -- 
> 2.7.4
>