[PATCH 0/7] Collection of small fixes and updates

[PATCH 0/7] Collection of small fixes and updates

[Akira Yokosawa]

Hi Paul,
(Cc: Junchang, Elad)

I've got somewhat distracted and couldn't properly compose change logs
of patches I collected in a work-in-progress branch.
Finally I managed to update the style guide to reflect enhancements in
fcvextract.pl and amend the commit logs.

Patch #1 was the one presented to Junchang as an example to combine
two code fragments in a code snippet.
Patch #2 applies the new scheme to another fragment in rcu_nest.h,
which was updated by Junchang.
Patch #3 fixes type reported by Elad.
Patch #4 updates FAQ-BUILD.txt for F29 and F30 users.
Patch #5 removes remnant of quantum computing.
Patch #6 applies the new scheme to another fragment in rcu.h, which
was also updated by Junchang.
Patch #7 is the update of style guide

Patches #1, #2, #3, and #6 are CC'd to Junchang or Elad.
I don't think their Acks are musts in these cases, but would highly
appreciate them.

        Thanks, Akira
--
Akira Yokosawa (7):
  toyrcu: Convert Listing B.1 to new scheme
  toyrcu: Extract Listing B.15 from rcu_nest.h
  toolsoftrade: Fix typo
  FAQ-BUILD: Update for recent Fedora releases
  howto: Stop mentioning quantum computing
  toyrcu: Extract Listing B.13 from rcu.h
  styleguide: Update description of available options to \begin{snippet}

 CodeSamples/defer/rcu.h                 |  2 +
 CodeSamples/defer/rcu_lock.c            |  2 +
 CodeSamples/defer/rcu_lock.h            |  2 +
 CodeSamples/defer/rcu_nest.h            |  2 +
 FAQ-BUILD.txt                           |  9 +--
 appendix/styleguide/samplecodesnippet.c |  2 +-
 appendix/styleguide/styleguide.tex      | 76 +++++++++++++++----------
 appendix/toyrcu/toyrcu.tex              | 50 ++--------------
 howto/howto.tex                         |  2 +-
 toolsoftrade/toolsoftrade.tex           |  2 +-
 10 files changed, 66 insertions(+), 83 deletions(-)

-- 
2.17.1

[PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme

[Akira Yokosawa]

From 245899f43fd007aa344180c0089515cd90f84db2 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sat, 27 Apr 2019 21:04:40 +0900
Subject: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme

This commit was originally presented to Junchang as an example where
code fragments extracted from two source files under CodeSamples/ are
merged into a code snippet.

Junchan employed this scheme in commits 686f3f3b721c ("rcu: Use
READ_ONCE() and WRITE_ONCE() for shared variable rcu_gp_ctr"),
a26c1625bb0d ("rcu_qs: Use READ_ONCE() AND WRITE_ONCE() for shared
variable rcu_gp_ctr"), and b9696a4a456f ("rcu_nest: Update description
of rcu_nest.[hc]").

Extra vertical space needs to be canceled by the \vspace*{} command
between the two \input{} commands.
\fvset{firstnumber=last} is to continue line numbering.
\fvset{firstnumber=auto} restores the default setting.

Also tweak positioning option of the listing environment.

Cc: Junchang Wang <junchangwang@gmail.com>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 CodeSamples/defer/rcu_lock.c |  2 ++
 CodeSamples/defer/rcu_lock.h |  2 ++
 appendix/toyrcu/toyrcu.tex   | 26 ++++----------------------
 3 files changed, 8 insertions(+), 22 deletions(-)

diff --git a/CodeSamples/defer/rcu_lock.c b/CodeSamples/defer/rcu_lock.c
index 8d45ac89..08b87fbd 100644
--- a/CodeSamples/defer/rcu_lock.c
+++ b/CodeSamples/defer/rcu_lock.c
@@ -20,12 +20,14 @@
 
 #include "../api.h"
 #include "rcu_lock.h"
+//\begin{snippet}[labelbase=ln:defer:rcu_lock:synchronize,commandchars=\\\[\]]
 
 void synchronize_rcu(void)
 {
 	spin_lock(&rcu_gp_lock);
 	spin_unlock(&rcu_gp_lock);
 }
+//\end{snippet}
 
 #ifdef TEST
 #include "rcutorture.h"
diff --git a/CodeSamples/defer/rcu_lock.h b/CodeSamples/defer/rcu_lock.h
index 224ea0e4..bf6f9b3c 100644
--- a/CodeSamples/defer/rcu_lock.h
+++ b/CodeSamples/defer/rcu_lock.h
@@ -26,6 +26,7 @@ static void rcu_init(void)
 {
 }
 
+//\begin{snippet}[labelbase=ln:defer:rcu_lock:lock_unlock,commandchars=\\\[\]]
 static void rcu_read_lock(void)
 {
 	spin_lock(&rcu_gp_lock);
@@ -35,5 +36,6 @@ static void rcu_read_unlock(void)
 {
 	spin_unlock(&rcu_gp_lock);
 }
+//\end{snippet}
 
 extern void synchronize_rcu(void);
diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
index 0e84b058..d876595b 100644
--- a/appendix/toyrcu/toyrcu.tex
+++ b/appendix/toyrcu/toyrcu.tex
@@ -30,29 +30,11 @@ provides a summary and a list of desirable RCU properties.
 
 \section{Lock-Based RCU}
 \label{sec:app:toyrcu:Lock-Based RCU}
+\NoIndentAfterThis
 
-\begin{listing}[bp]
-{ \scriptsize
-\begin{verbbox}
-  1 static void rcu_read_lock(void)
-  2 {
-  3   spin_lock(&rcu_gp_lock);
-  4 }
-  5
-  6 static void rcu_read_unlock(void)
-  7 {
-  8   spin_unlock(&rcu_gp_lock);
-  9 }
- 10
- 11 void synchronize_rcu(void)
- 12 {
- 13   spin_lock(&rcu_gp_lock);
- 14   spin_unlock(&rcu_gp_lock);
- 15 }
-\end{verbbox}
-}
-\centering
-\theverbbox
+\begin{listing}[htbp]
+\input{CodeSamples/defer/rcu_lock@lock_unlock.fcv}\vspace*{-11pt}\fvset{firstnumber=last}
+\input{CodeSamples/defer/rcu_lock@synchronize.fcv}\fvset{firstnumber=auto}
 \caption{Lock-Based RCU Implementation}
 \label{lst:app:toyrcu:Lock-Based RCU Implementation}
 \end{listing}
-- 
2.17.1

[PATCH 2/7] toyrcu: Extract Listing B.15 from rcu_nest.h

[Akira Yokosawa]

From d89573cab1299a8b8dfc731caa24057249c88296 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 2 Jun 2019 23:55:49 +0900
Subject: [PATCH 2/7] toyrcu: Extract Listing B.15 from rcu_nest.h

Commit b9696a4a456f ("rcu_nest: Update description of rcu_nest.[hc]")
updated B.16 to reflect the changes in rcu_nest.[hc]. For consistency,
extract Listing B.15 from rcu_nest.h.

Cc: Junchang Wang <junchangwang@gmail.com>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 CodeSamples/defer/rcu_nest.h |  2 ++
 appendix/toyrcu/toyrcu.tex   | 13 +------------
 2 files changed, 3 insertions(+), 12 deletions(-)

diff --git a/CodeSamples/defer/rcu_nest.h b/CodeSamples/defer/rcu_nest.h
index 19a09568..3c5a5207 100644
--- a/CodeSamples/defer/rcu_nest.h
+++ b/CodeSamples/defer/rcu_nest.h
@@ -24,6 +24,7 @@
 #define ULONG_CMP_GE(a, b)      (ULONG_MAX / 2 >= (a) - (b))
 #define ULONG_CMP_LT(a, b)      (ULONG_MAX / 2 < (a) - (b))
 
+//\begin{snippet}[labelbase=ln:defer:rcu_nest:define,commandchars=\%\@\$]
 DEFINE_SPINLOCK(rcu_gp_lock);
 #define RCU_GP_CTR_SHIFT 7
 #define RCU_GP_CTR_BOTTOM_BIT (1 << RCU_GP_CTR_SHIFT)
@@ -31,6 +32,7 @@ DEFINE_SPINLOCK(rcu_gp_lock);
 #define MAX_GP_ADV_DISTANCE (RCU_GP_CTR_NEST_MASK << 8)
 unsigned long rcu_gp_ctr = 0;	/* increment by RCU_GP_CTR_BOTTOM_BIT each gp. */
 DEFINE_PER_THREAD(unsigned long, rcu_reader_gp);
+//\end{snippet}
 
 static inline int rcu_gp_ongoing(int cpu)
 {
diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
index d876595b..81f222c6 100644
--- a/appendix/toyrcu/toyrcu.tex
+++ b/appendix/toyrcu/toyrcu.tex
@@ -1360,18 +1360,7 @@ variables.
 \label{sec:app:toyrcu:Nestable RCU Based on Free-Running Counter}
 
 \begin{listing}[tb]
-{ \scriptsize
-\begin{verbbox}
-  1 DEFINE_SPINLOCK(rcu_gp_lock);
-  2 #define RCU_GP_CTR_SHIFT 7
-  3 #define RCU_GP_CTR_BOTTOM_BIT (1 << RCU_GP_CTR_SHIFT)
-  4 #define RCU_GP_CTR_NEST_MASK (RCU_GP_CTR_BOTTOM_BIT - 1)
-  5 long rcu_gp_ctr = 0;
-  6 DEFINE_PER_THREAD(long, rcu_reader_gp);
-\end{verbbox}
-}
-\centering
-\theverbbox
+\input{CodeSamples/defer/rcu_nest@define.fcv}
 \caption{Data for Nestable RCU Using a Free-Running Counter}
 \label{lst:app:toyrcu:Data for Nestable RCU Using a Free-Running Counter}
 \end{listing}
-- 
2.17.1

[PATCH 3/7] toolsoftrade: Fix typo

[Akira Yokosawa]

From 66874f5a6cd1b758cdc442084e28289ef12aa082 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 2 Jun 2019 23:21:02 +0900
Subject: [PATCH 3/7] toolsoftrade: Fix typo

Elad reported this typo quite a while ago [1]. Given that it hasn't
been taken care of, let's fix it.

[1]: https://www.spinics.net/lists/perfbook/msg02318.html

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

diff --git a/toolsoftrade/toolsoftrade.tex b/toolsoftrade/toolsoftrade.tex
index 9f636931..6ad5ebb6 100644
--- a/toolsoftrade/toolsoftrade.tex
+++ b/toolsoftrade/toolsoftrade.tex
@@ -1550,7 +1550,7 @@ Of course, where practical, the primitives described in
 Section~\ref{sec:toolsoftrade:Atomic Operations (gcc Classic)}
 or (especially)
 Section~\ref{sec:toolsoftrade:Atomic Operations (C11)}
-should be instead be used to avoid data races, that is, to ensure
+should instead be used to avoid data races, that is, to ensure
 that if there are multiple concurrent accesses to a given
 variable, all of those accesses are loads.
 
-- 
2.17.1

[PATCH 4/7] FAQ-BUILD: Update for recent Fedora releases

[Akira Yokosawa]

From 4ae74b9f60e29298d3d67736db9a2baa19655842 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 5 May 2019 00:22:28 +0900
Subject: [PATCH 4/7] FAQ-BUILD: Update for recent Fedora releases

Also remove info for Ubuntu Trusty.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 FAQ-BUILD.txt | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/FAQ-BUILD.txt b/FAQ-BUILD.txt
index 012a1d69..82cca6e8 100644
--- a/FAQ-BUILD.txt
+++ b/FAQ-BUILD.txt
@@ -44,9 +44,6 @@
 			texlive-science texlive-bibtex-extra
 			gnuplot-x11 xfig inkscape graphviz fig2ps
 
-		On Ubuntu Trusty, in addition to the above, you need:
-			texlive-humanities
-
 		On Ubuntu Bionic, the following list should cover
 		necessary packages (except for -doc packages):
 			texlive-publishers texlive-pstricks
@@ -57,16 +54,14 @@
 		compatible with updated Ghostscript (not limited to
 		Ubuntu Bionic). See #7 below.
 
-		On Fedora 28 and 27, installing the following set of
+		On Fedora 30 and 29, installing the following set of
 		packages suffices:
+			texlive-collection-plaingeneric
 			texlive-collection-binextra
 			texlive-collection-latexextra
 			texlive-collection-fontsextra
 			fig2ps graphviz inkscape
 
-		You need to install a version of a2ping compatible
-		with Ghostscript 9.22 or later. See #7 below.
-
 		On other Linux distributions such as RHEL/CentOS and
 		Scientific Linux, where support of TeX Live packages
 		is insufficient, manually installing TeX Live should
-- 
2.17.1

[PATCH 5/7] howto: Stop mentioning quantum computing

[Akira Yokosawa]

From 2aadd71518c8dda2748541618038c495903ee9da Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Mon, 6 May 2019 00:02:22 +0900
Subject: [PATCH 5/7] howto: Stop mentioning quantum computing

Paul gave up tracing quantum computing as of commit 972946a5298a
("future/QC: Remove quantum-computing section"). Remove it.

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

diff --git a/howto/howto.tex b/howto/howto.tex
index 5fcc1e5e..3bdec595 100644
--- a/howto/howto.tex
+++ b/howto/howto.tex
@@ -119,7 +119,7 @@ Chapter~\ref{chp:Ease of Use} follows up with some ease-of-use advice.
 Finally, Chapter~\ref{chp:Conflicting Visions of the Future}
 looks at a few possible future directions, including
 shared-memory parallel system design, software and hardware transactional
-memory, functional programming for parallelism, and quantum computing.
+memory, and functional programming for parallelism.
 
 This chapter is followed by a number of appendices.
 The most popular of these appears to be
-- 
2.17.1

[PATCH 6/7] toyrcu: Extract Listing B.13 from rcu.h

[Akira Yokosawa]

From f37685cb3821daf0d9ee55a538ec462e5de0a6a8 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Tue, 4 Jun 2019 00:35:02 +0900
Subject: [PATCH 6/7] toyrcu: Extract Listing B.13 from rcu.h

Commit 686f3f3b721c ("rcu: Use READ_ONCE() and WRITE_ONCE() for
shared variable rcu_gp_ctr") updated B.14 to reflect the changes
in rcu.[hc]. For consistency, extract Listing B.13 from rcu.h.

Cc: Junchang Wang <junchangwang@gmail.com>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 CodeSamples/defer/rcu.h    |  2 ++
 appendix/toyrcu/toyrcu.tex | 11 +----------
 2 files changed, 3 insertions(+), 10 deletions(-)

diff --git a/CodeSamples/defer/rcu.h b/CodeSamples/defer/rcu.h
index 3641c33a..b3c3e2c4 100644
--- a/CodeSamples/defer/rcu.h
+++ b/CodeSamples/defer/rcu.h
@@ -20,10 +20,12 @@
 
 #include "rcu_pointer.h"
 
+//\begin{snippet}[labelbase=ln:defer:rcu:define,commandchars=\%\@\$]
 DEFINE_SPINLOCK(rcu_gp_lock);
 long rcu_gp_ctr = 0;	/* always even, +=2 at start of each grace period. */
 DEFINE_PER_THREAD(long, rcu_reader_gp);
 DEFINE_PER_THREAD(long, rcu_reader_gp_snap);
+//\end{snippet}
 
 static inline void rcu_init(void)
 {
diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
index 81f222c6..f6ce2bee 100644
--- a/appendix/toyrcu/toyrcu.tex
+++ b/appendix/toyrcu/toyrcu.tex
@@ -1185,16 +1185,7 @@ thread-local accesses to one, as is done in the next section.
 \label{sec:app:toyrcu:RCU Based on Free-Running Counter}
 
 \begin{listing}[tbp]
-{ \scriptsize
-\begin{verbbox}
-  1 DEFINE_SPINLOCK(rcu_gp_lock);
-  2 long rcu_gp_ctr = 0;
-  3 DEFINE_PER_THREAD(long, rcu_reader_gp);
-  4 DEFINE_PER_THREAD(long, rcu_reader_gp_snap);
-\end{verbbox}
-}
-\centering
-\theverbbox
+\input{CodeSamples/defer/rcu@define.fcv}
 \caption{Data for Free-Running Counter Using RCU}
 \label{lst:app:toyrcu:Data for Free-Running Counter Using RCU}
 \end{listing}
-- 
2.17.1

[PATCH 7/7] styleguide: Update description of available options to \begin{snippet}

[Akira Yokosawa]

From f781e599d428ed061c34159697d7ebf3c32927c8 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Mon, 15 Jul 2019 22:51:33 +0900
Subject: [PATCH 7/7] styleguide: Update description of available options to \begin{snippet}

Update the list of commands and options recognized by fcvextract.pl.
Now that the default is to remove comment blocks in code snippets,
we need the "keepcomment=yes" option in Listing B.3.
Also use American spelling of "flavor".

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 appendix/styleguide/samplecodesnippet.c |  2 +-
 appendix/styleguide/styleguide.tex      | 76 +++++++++++++++----------
 2 files changed, 48 insertions(+), 30 deletions(-)

diff --git a/appendix/styleguide/samplecodesnippet.c b/appendix/styleguide/samplecodesnippet.c
index f58f6568..37885a12 100644
--- a/appendix/styleguide/samplecodesnippet.c
+++ b/appendix/styleguide/samplecodesnippet.c
@@ -1,4 +1,4 @@
-//\begin{snippet}[labelbase=ln:base1,commandchars=\$\[\]]
+//\begin{snippet}[labelbase=ln:base1,keepcomment=yes,commandchars=\$\[\]]
 /*
  * Sample Code Snippet
  */
diff --git a/appendix/styleguide/styleguide.tex b/appendix/styleguide/styleguide.tex
index 7cd05102..e5ca7aaa 100644
--- a/appendix/styleguide/styleguide.tex
+++ b/appendix/styleguide/styleguide.tex
@@ -330,20 +330,20 @@ The goal of the new scheme is to extract \LaTeX\ sources of
 code snippets directly from code samples under \path{CodeSamples}
 directory.
 It also makes it possible to embed line labels in the code samples,
-which can be referred from the text.
+which can be referenced within the \LaTeX\ sources.
 This reduces the burden of keeping line numbers
 in the text consistent with those in code snippets.
 
 Code-snippet extraction is handled by a couple of
 perl scripts and recipes in Makefile.
-We use the \co{fancyvrb} package's escaping feature
-to embed line labels in comments.
+We use the escaping feature of the \co{fancyvrb} package
+to embed line labels as comments.
 
 We used to use the \qco{verbbox} environment provided
 by the \qco{verbatimbox} package.
 Section~\ref{sec:app:styleguide:Code Snippet (Obsolete)} describes how
 \co{verbbox} can automatically generate line numbers,
-but these line numbers cannot be referenced from the text.
+but those line numbers cannot be referenced within the \LaTeX\ sources.
 
 Let's start by looking at how code snippets are coded in the new scheme.
 There are three customized environments of \qco{Verbatim}.
@@ -448,45 +448,63 @@ are described as recipes in the top level \path{Makefile} and
 a script to generate dependencies (\path{utilities/gen_snippet_d.pl}).
 \end{lineref}
 
-\begin{listing}[tb]
+\begin{listing*}[tb]
 \fvset{fontsize=\scriptsize,numbers=left,numbersep=5pt,xleftmargin=9pt,obeytabs=true,tabsize=8}
 \VerbatimInput{appendix/styleguide/samplecodesnippet.c}
 \vspace*{-9pt}
-\caption{Source of Code Sample with ``snippet'' meta command}
+\caption{Source of Code Sample with ``snippet'' Meta Command}
 \label{lst:app:styleguide:Source of Code Sample}
-\end{listing}
+\end{listing*}
 
 As you can see, Listing ~\ref{lst:app:styleguide:Source of Code Sample}
 has meta commands in comments of C (C++ style). Those meta commands
 are interpreted by \path{utilities/fcvextract.pl}, which distinguishes
 the type of comment style by the suffix of code sample's file name.
 
-Meta commands which can be used in code samples are shown below:
+Meta commands which can be used in code samples are listed below:
 
-\begin{VerbatimU}
-\begin{snippet}[option]
-\end{snippet}
-\lnlbl{<label string>}
-\end{VerbatimU}
+\begin{itemize}[noitemsep]
+\item \co{\\begin\{snippet\}[<options>]}
+\item \co{\\end\{snippet\}}
+\item \co{\\lnlbl\{<label string>\}}
+\item \co{\\fcvexclude}
+\item \co{\\fcvblank}
+\end{itemize}
 
-Options to the \co{\\begin\{snippet\}} meta command are as the following:
+\qco{<options>} to the \co{\\begin\{snippet\}} meta command
+is a comma-spareted list of options shown below:
 
-\begin{VerbatimU}
-labelbase=<label base string>
-commandchars=\X\Y\Z
-\end{VerbatimU}
+\begin{itemize}[noitemsep]
+\item \co{labelbase=<label base string>}
+\item \co{keepcomment=yes}
+\item \co{gobbleblank=yes}
+\item \co{commandchars=\\X\\Y\\Z}
+\end{itemize}
 
-The string given to \qco{labelbase} will be passed to
+The \qco{labelbase} option is mandatory and the string given to it
+will be passed to the
 ``\co{\\begin\{linelabel\}[<label base string>]}'' command as shown on
 line~\ref{ln:app:styleguide:LaTeX Source of Sample Code Snippet (Current):beg:linelabel} of
 Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}.
-\qco{commandchars} option is given to the \co{VerbatimL} environment as is.
+The \qco{keepcomment=yes} option tells \co{fcvextract.pl} to keep
+comment blocks.
+Otherwise, comment blocks in C source code will be omitted.
+The \qco{gobbleblank=yes} option will remove empty or blank lines
+in the resulting snippet.
+The \qco{commandchars} option is given to the \co{VerbatimL} environment
+as is. At the moment, it is also mandatory
+and must come at the end of options listed above.
 Other types of options, if any, are also passed to the \co{VerbatimL}
 environment.
-The \qco{lnlbl} commands are converted along the way to reflect
+
+The \qco{\lnlbl} commands are converted along the way to reflect
 the escape-character choice.\footnote{
-	Characters forming comments are also gobbled up.
+	Characters forming comments around the \qco{\lnlbl} commands
+	are also gobbled up regardless of the \qco{keepcomment} setting.
 }
+Source lines with \qco{\fcvexclude} are removed.
+\qco{\fcvblank} can be used to keep blank lines when the
+\qco{gobbleblank=yes} option is specified.
 
 There can be multiple pairs of \co{\\begin\{snippet\}} and \co{\\end\{snippet\}}
 as long as they have unique \qco{labelbase} strings.
@@ -498,25 +516,25 @@ ln:<Chapter/Subdirectory>:<File Name>:<Function Name>
 \end{VerbatimU}
 
 Litmus tests, which are handled by \qco{herdtools7} commands such as
-\qco{litmus7} and \qco{herd7}, were problematic for this scheme.
+\qco{litmus7} and \qco{herd7}, were problematic in this scheme.
 Those commands have particular rules of where comments can be
-placed and restriction on characters in comments.
+placed and restriction on permitted characters in comments.
 They also forbid a couple of tokens to appear in comments.
 (Tokens in comments might sound strange, but they do have such restriction.)
 
 For example, the first token in a litmus test must be one of
 \qco{C}, \qco{PPC}, \qco{X86}, \qco{LISA}, etc., which indicates
-the flavour of the test. This means no comment is allowed
+the flavor of the test. This means no comment is allowed
 at the beginning of a litmus test.
 
 Similarly, several tokens such as \qco{exists}, \qco{filter},
 and~\qco{locations} indicate the end of litmus test's body.
-Once one of them appears in a litmus test, comments should be
+Once one of them appears in a litmus test, comments should be of
 ocaml style (\qco{(* ... *)}). Those tokens keep the same meaning
 even when they appear in comments!
 
 The pair of characters ``\co{\{}'' and ``\co{\}}'' also have special
-meaning in the C flavour tests. They are used to seperate portions
+meaning in the C flavor tests. They are used to seperate portions
 in a litmus test.
 
 First pair of ``\co{\{}'' and ``\co{\}}'' encloses initialization part.
@@ -548,7 +566,7 @@ exists (0:r1=0)  // C++ style comment after test body
 \end{VerbatimN}
 \end{linelabel}
 
-To avoid parse errors, meta commands in litmus tests (C flavour) are embedded
+To avoid parse errors, meta commands in litmus tests (C flavor) are embedded
 in the following way.
 
 \begin{linelabel}[ln:app:styleguide:Sample Source of Litmus Test]
@@ -583,7 +601,7 @@ exists (1:r2=0 /\ 0:r2=0)  (* \lnlbl[exists_] *)
 
 Example above is converted to the following intermediate code
 by a script \path{utilities/reorder_ltms.pl}.\footnote{
-	Currently, only C flavour litmus tests are supported.
+	Currently, only C flavor litmus tests are supported.
 }
 The intermediate code can be handled
 by the common script \path{utilities/fcvextract.pl}.
-- 
2.17.1

Re: [PATCH 0/7] Collection of small fixes and updates

[Akira Yokosawa]

On 2019/07/21 8:59, Akira Yokosawa wrote:
> Hi Paul,
> (Cc: Junchang, Elad)
> 
> I've got somewhat distracted and couldn't properly compose change logs
> of patches I collected in a work-in-progress branch.
> Finally I managed to update the style guide to reflect enhancements in
> fcvextract.pl and amend the commit logs.
> 
> Patch #1 was the one presented to Junchang as an example to combine
> two code fragments in a code snippet.
> Patch #2 applies the new scheme to another fragment in rcu_nest.h,
> which was updated by Junchang.
> Patch #3 fixes type reported by Elad.
> Patch #4 updates FAQ-BUILD.txt for F29 and F30 users.
> Patch #5 removes remnant of quantum computing.
> Patch #6 applies the new scheme to another fragment in rcu.h, which
> was also updated by Junchang.
> Patch #7 is the update of style guide
> 
> Patches #1, #2, #3, and #6 are CC'd to Junchang or Elad.
Oops, looks like Patch #4 was CC'd to Junchang and Elad.
Junchang, Elad, Please ignore it.

        Thanks, Akira

> I don't think their Acks are musts in these cases, but would highly
> appreciate them.
> 
>         Thanks, Akira
> --
> Akira Yokosawa (7):
>   toyrcu: Convert Listing B.1 to new scheme
>   toyrcu: Extract Listing B.15 from rcu_nest.h
>   toolsoftrade: Fix typo
>   FAQ-BUILD: Update for recent Fedora releases
>   howto: Stop mentioning quantum computing
>   toyrcu: Extract Listing B.13 from rcu.h
>   styleguide: Update description of available options to \begin{snippet}
> 
>  CodeSamples/defer/rcu.h                 |  2 +
>  CodeSamples/defer/rcu_lock.c            |  2 +
>  CodeSamples/defer/rcu_lock.h            |  2 +
>  CodeSamples/defer/rcu_nest.h            |  2 +
>  FAQ-BUILD.txt                           |  9 +--
>  appendix/styleguide/samplecodesnippet.c |  2 +-
>  appendix/styleguide/styleguide.tex      | 76 +++++++++++++++----------
>  appendix/toyrcu/toyrcu.tex              | 50 ++--------------
>  howto/howto.tex                         |  2 +-
>  toolsoftrade/toolsoftrade.tex           |  2 +-
>  10 files changed, 66 insertions(+), 83 deletions(-)
> 

Re: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme

[Junchang Wang]

Hi Akira,

Thanks for the patch. The new scheme worked great as a good example of
composing my commits. So,

Acked-by: Junchang Wang <junchangwang@gmail.com>


Thanks,
--Junchang

On Sun, Jul 21, 2019 at 8:02 AM Akira Yokosawa <akiyks@gmail.com> wrote:
>
> From 245899f43fd007aa344180c0089515cd90f84db2 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@gmail.com>
> Date: Sat, 27 Apr 2019 21:04:40 +0900
> Subject: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme
>
> This commit was originally presented to Junchang as an example where
> code fragments extracted from two source files under CodeSamples/ are
> merged into a code snippet.
>
> Junchan employed this scheme in commits 686f3f3b721c ("rcu: Use
> READ_ONCE() and WRITE_ONCE() for shared variable rcu_gp_ctr"),
> a26c1625bb0d ("rcu_qs: Use READ_ONCE() AND WRITE_ONCE() for shared
> variable rcu_gp_ctr"), and b9696a4a456f ("rcu_nest: Update description
> of rcu_nest.[hc]").
>
> Extra vertical space needs to be canceled by the \vspace*{} command
> between the two \input{} commands.
> \fvset{firstnumber=last} is to continue line numbering.
> \fvset{firstnumber=auto} restores the default setting.
>
> Also tweak positioning option of the listing environment.
>
> Cc: Junchang Wang <junchangwang@gmail.com>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
>  CodeSamples/defer/rcu_lock.c |  2 ++
>  CodeSamples/defer/rcu_lock.h |  2 ++
>  appendix/toyrcu/toyrcu.tex   | 26 ++++----------------------
>  3 files changed, 8 insertions(+), 22 deletions(-)
>
> diff --git a/CodeSamples/defer/rcu_lock.c b/CodeSamples/defer/rcu_lock.c
> index 8d45ac89..08b87fbd 100644
> --- a/CodeSamples/defer/rcu_lock.c
> +++ b/CodeSamples/defer/rcu_lock.c
> @@ -20,12 +20,14 @@
>
>  #include "../api.h"
>  #include "rcu_lock.h"
> +//\begin{snippet}[labelbase=ln:defer:rcu_lock:synchronize,commandchars=\\\[\]]
>
>  void synchronize_rcu(void)
>  {
>         spin_lock(&rcu_gp_lock);
>         spin_unlock(&rcu_gp_lock);
>  }
> +//\end{snippet}
>
>  #ifdef TEST
>  #include "rcutorture.h"
> diff --git a/CodeSamples/defer/rcu_lock.h b/CodeSamples/defer/rcu_lock.h
> index 224ea0e4..bf6f9b3c 100644
> --- a/CodeSamples/defer/rcu_lock.h
> +++ b/CodeSamples/defer/rcu_lock.h
> @@ -26,6 +26,7 @@ static void rcu_init(void)
>  {
>  }
>
> +//\begin{snippet}[labelbase=ln:defer:rcu_lock:lock_unlock,commandchars=\\\[\]]
>  static void rcu_read_lock(void)
>  {
>         spin_lock(&rcu_gp_lock);
> @@ -35,5 +36,6 @@ static void rcu_read_unlock(void)
>  {
>         spin_unlock(&rcu_gp_lock);
>  }
> +//\end{snippet}
>
>  extern void synchronize_rcu(void);
> diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
> index 0e84b058..d876595b 100644
> --- a/appendix/toyrcu/toyrcu.tex
> +++ b/appendix/toyrcu/toyrcu.tex
> @@ -30,29 +30,11 @@ provides a summary and a list of desirable RCU properties.
>
>  \section{Lock-Based RCU}
>  \label{sec:app:toyrcu:Lock-Based RCU}
> +\NoIndentAfterThis
>
> -\begin{listing}[bp]
> -{ \scriptsize
> -\begin{verbbox}
> -  1 static void rcu_read_lock(void)
> -  2 {
> -  3   spin_lock(&rcu_gp_lock);
> -  4 }
> -  5
> -  6 static void rcu_read_unlock(void)
> -  7 {
> -  8   spin_unlock(&rcu_gp_lock);
> -  9 }
> - 10
> - 11 void synchronize_rcu(void)
> - 12 {
> - 13   spin_lock(&rcu_gp_lock);
> - 14   spin_unlock(&rcu_gp_lock);
> - 15 }
> -\end{verbbox}
> -}
> -\centering
> -\theverbbox
> +\begin{listing}[htbp]
> +\input{CodeSamples/defer/rcu_lock@lock_unlock.fcv}\vspace*{-11pt}\fvset{firstnumber=last}
> +\input{CodeSamples/defer/rcu_lock@synchronize.fcv}\fvset{firstnumber=auto}
>  \caption{Lock-Based RCU Implementation}
>  \label{lst:app:toyrcu:Lock-Based RCU Implementation}
>  \end{listing}
> --
> 2.17.1
>
>

Re: [PATCH 2/7] toyrcu: Extract Listing B.15 from rcu_nest.h

[Junchang Wang]

Hi Akira,

Thanks for helping complete applying the new scheme on rcu_nest. The
patch looks good to me.

Thanks,
--Junchang

On Sun, Jul 21, 2019 at 8:03 AM Akira Yokosawa <akiyks@gmail.com> wrote:
>
> From d89573cab1299a8b8dfc731caa24057249c88296 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@gmail.com>
> Date: Sun, 2 Jun 2019 23:55:49 +0900
> Subject: [PATCH 2/7] toyrcu: Extract Listing B.15 from rcu_nest.h
>
> Commit b9696a4a456f ("rcu_nest: Update description of rcu_nest.[hc]")
> updated B.16 to reflect the changes in rcu_nest.[hc]. For consistency,
> extract Listing B.15 from rcu_nest.h.
>
> Cc: Junchang Wang <junchangwang@gmail.com>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
>  CodeSamples/defer/rcu_nest.h |  2 ++
>  appendix/toyrcu/toyrcu.tex   | 13 +------------
>  2 files changed, 3 insertions(+), 12 deletions(-)
>
> diff --git a/CodeSamples/defer/rcu_nest.h b/CodeSamples/defer/rcu_nest.h
> index 19a09568..3c5a5207 100644
> --- a/CodeSamples/defer/rcu_nest.h
> +++ b/CodeSamples/defer/rcu_nest.h
> @@ -24,6 +24,7 @@
>  #define ULONG_CMP_GE(a, b)      (ULONG_MAX / 2 >= (a) - (b))
>  #define ULONG_CMP_LT(a, b)      (ULONG_MAX / 2 < (a) - (b))
>
> +//\begin{snippet}[labelbase=ln:defer:rcu_nest:define,commandchars=\%\@\$]
>  DEFINE_SPINLOCK(rcu_gp_lock);
>  #define RCU_GP_CTR_SHIFT 7
>  #define RCU_GP_CTR_BOTTOM_BIT (1 << RCU_GP_CTR_SHIFT)
> @@ -31,6 +32,7 @@ DEFINE_SPINLOCK(rcu_gp_lock);
>  #define MAX_GP_ADV_DISTANCE (RCU_GP_CTR_NEST_MASK << 8)
>  unsigned long rcu_gp_ctr = 0;  /* increment by RCU_GP_CTR_BOTTOM_BIT each gp. */
>  DEFINE_PER_THREAD(unsigned long, rcu_reader_gp);
> +//\end{snippet}
>
>  static inline int rcu_gp_ongoing(int cpu)
>  {
> diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
> index d876595b..81f222c6 100644
> --- a/appendix/toyrcu/toyrcu.tex
> +++ b/appendix/toyrcu/toyrcu.tex
> @@ -1360,18 +1360,7 @@ variables.
>  \label{sec:app:toyrcu:Nestable RCU Based on Free-Running Counter}
>
>  \begin{listing}[tb]
> -{ \scriptsize
> -\begin{verbbox}
> -  1 DEFINE_SPINLOCK(rcu_gp_lock);
> -  2 #define RCU_GP_CTR_SHIFT 7
> -  3 #define RCU_GP_CTR_BOTTOM_BIT (1 << RCU_GP_CTR_SHIFT)
> -  4 #define RCU_GP_CTR_NEST_MASK (RCU_GP_CTR_BOTTOM_BIT - 1)
> -  5 long rcu_gp_ctr = 0;
> -  6 DEFINE_PER_THREAD(long, rcu_reader_gp);
> -\end{verbbox}
> -}
> -\centering
> -\theverbbox
> +\input{CodeSamples/defer/rcu_nest@define.fcv}
>  \caption{Data for Nestable RCU Using a Free-Running Counter}
>  \label{lst:app:toyrcu:Data for Nestable RCU Using a Free-Running Counter}
>  \end{listing}
> --
> 2.17.1
>
>

Re: [PATCH 6/7] toyrcu: Extract Listing B.13 from rcu.h

[Junchang Wang]

This patch also looks good to me. Thanks, Akira!

--Junchang

On Sun, Jul 21, 2019 at 8:12 AM Akira Yokosawa <akiyks@gmail.com> wrote:
>
> From f37685cb3821daf0d9ee55a538ec462e5de0a6a8 Mon Sep 17 00:00:00 2001
> From: Akira Yokosawa <akiyks@gmail.com>
> Date: Tue, 4 Jun 2019 00:35:02 +0900
> Subject: [PATCH 6/7] toyrcu: Extract Listing B.13 from rcu.h
>
> Commit 686f3f3b721c ("rcu: Use READ_ONCE() and WRITE_ONCE() for
> shared variable rcu_gp_ctr") updated B.14 to reflect the changes
> in rcu.[hc]. For consistency, extract Listing B.13 from rcu.h.
>
> Cc: Junchang Wang <junchangwang@gmail.com>
> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> ---
>  CodeSamples/defer/rcu.h    |  2 ++
>  appendix/toyrcu/toyrcu.tex | 11 +----------
>  2 files changed, 3 insertions(+), 10 deletions(-)
>
> diff --git a/CodeSamples/defer/rcu.h b/CodeSamples/defer/rcu.h
> index 3641c33a..b3c3e2c4 100644
> --- a/CodeSamples/defer/rcu.h
> +++ b/CodeSamples/defer/rcu.h
> @@ -20,10 +20,12 @@
>
>  #include "rcu_pointer.h"
>
> +//\begin{snippet}[labelbase=ln:defer:rcu:define,commandchars=\%\@\$]
>  DEFINE_SPINLOCK(rcu_gp_lock);
>  long rcu_gp_ctr = 0;   /* always even, +=2 at start of each grace period. */
>  DEFINE_PER_THREAD(long, rcu_reader_gp);
>  DEFINE_PER_THREAD(long, rcu_reader_gp_snap);
> +//\end{snippet}
>
>  static inline void rcu_init(void)
>  {
> diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
> index 81f222c6..f6ce2bee 100644
> --- a/appendix/toyrcu/toyrcu.tex
> +++ b/appendix/toyrcu/toyrcu.tex
> @@ -1185,16 +1185,7 @@ thread-local accesses to one, as is done in the next section.
>  \label{sec:app:toyrcu:RCU Based on Free-Running Counter}
>
>  \begin{listing}[tbp]
> -{ \scriptsize
> -\begin{verbbox}
> -  1 DEFINE_SPINLOCK(rcu_gp_lock);
> -  2 long rcu_gp_ctr = 0;
> -  3 DEFINE_PER_THREAD(long, rcu_reader_gp);
> -  4 DEFINE_PER_THREAD(long, rcu_reader_gp_snap);
> -\end{verbbox}
> -}
> -\centering
> -\theverbbox
> +\input{CodeSamples/defer/rcu@define.fcv}
>  \caption{Data for Free-Running Counter Using RCU}
>  \label{lst:app:toyrcu:Data for Free-Running Counter Using RCU}
>  \end{listing}
> --
> 2.17.1
>
>

Re: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme

[Paul E. McKenney]

On Sun, Jul 21, 2019 at 08:07:11PM +0800, Junchang Wang wrote:
> Hi Akira,
> 
> Thanks for the patch. The new scheme worked great as a good example of
> composing my commits. So,
> 
> Acked-by: Junchang Wang <junchangwang@gmail.com>

Thank you both!  I have queued and pushed this series, with Junchang's
ack on this patch.

							Thanx, Paul

> Thanks,
> --Junchang
> 
> On Sun, Jul 21, 2019 at 8:02 AM Akira Yokosawa <akiyks@gmail.com> wrote:
> >
> > From 245899f43fd007aa344180c0089515cd90f84db2 Mon Sep 17 00:00:00 2001
> > From: Akira Yokosawa <akiyks@gmail.com>
> > Date: Sat, 27 Apr 2019 21:04:40 +0900
> > Subject: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme
> >
> > This commit was originally presented to Junchang as an example where
> > code fragments extracted from two source files under CodeSamples/ are
> > merged into a code snippet.
> >
> > Junchan employed this scheme in commits 686f3f3b721c ("rcu: Use
> > READ_ONCE() and WRITE_ONCE() for shared variable rcu_gp_ctr"),
> > a26c1625bb0d ("rcu_qs: Use READ_ONCE() AND WRITE_ONCE() for shared
> > variable rcu_gp_ctr"), and b9696a4a456f ("rcu_nest: Update description
> > of rcu_nest.[hc]").
> >
> > Extra vertical space needs to be canceled by the \vspace*{} command
> > between the two \input{} commands.
> > \fvset{firstnumber=last} is to continue line numbering.
> > \fvset{firstnumber=auto} restores the default setting.
> >
> > Also tweak positioning option of the listing environment.
> >
> > Cc: Junchang Wang <junchangwang@gmail.com>
> > Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> > ---
> >  CodeSamples/defer/rcu_lock.c |  2 ++
> >  CodeSamples/defer/rcu_lock.h |  2 ++
> >  appendix/toyrcu/toyrcu.tex   | 26 ++++----------------------
> >  3 files changed, 8 insertions(+), 22 deletions(-)
> >
> > diff --git a/CodeSamples/defer/rcu_lock.c b/CodeSamples/defer/rcu_lock.c
> > index 8d45ac89..08b87fbd 100644
> > --- a/CodeSamples/defer/rcu_lock.c
> > +++ b/CodeSamples/defer/rcu_lock.c
> > @@ -20,12 +20,14 @@
> >
> >  #include "../api.h"
> >  #include "rcu_lock.h"
> > +//\begin{snippet}[labelbase=ln:defer:rcu_lock:synchronize,commandchars=\\\[\]]
> >
> >  void synchronize_rcu(void)
> >  {
> >         spin_lock(&rcu_gp_lock);
> >         spin_unlock(&rcu_gp_lock);
> >  }
> > +//\end{snippet}
> >
> >  #ifdef TEST
> >  #include "rcutorture.h"
> > diff --git a/CodeSamples/defer/rcu_lock.h b/CodeSamples/defer/rcu_lock.h
> > index 224ea0e4..bf6f9b3c 100644
> > --- a/CodeSamples/defer/rcu_lock.h
> > +++ b/CodeSamples/defer/rcu_lock.h
> > @@ -26,6 +26,7 @@ static void rcu_init(void)
> >  {
> >  }
> >
> > +//\begin{snippet}[labelbase=ln:defer:rcu_lock:lock_unlock,commandchars=\\\[\]]
> >  static void rcu_read_lock(void)
> >  {
> >         spin_lock(&rcu_gp_lock);
> > @@ -35,5 +36,6 @@ static void rcu_read_unlock(void)
> >  {
> >         spin_unlock(&rcu_gp_lock);
> >  }
> > +//\end{snippet}
> >
> >  extern void synchronize_rcu(void);
> > diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
> > index 0e84b058..d876595b 100644
> > --- a/appendix/toyrcu/toyrcu.tex
> > +++ b/appendix/toyrcu/toyrcu.tex
> > @@ -30,29 +30,11 @@ provides a summary and a list of desirable RCU properties.
> >
> >  \section{Lock-Based RCU}
> >  \label{sec:app:toyrcu:Lock-Based RCU}
> > +\NoIndentAfterThis
> >
> > -\begin{listing}[bp]
> > -{ \scriptsize
> > -\begin{verbbox}
> > -  1 static void rcu_read_lock(void)
> > -  2 {
> > -  3   spin_lock(&rcu_gp_lock);
> > -  4 }
> > -  5
> > -  6 static void rcu_read_unlock(void)
> > -  7 {
> > -  8   spin_unlock(&rcu_gp_lock);
> > -  9 }
> > - 10
> > - 11 void synchronize_rcu(void)
> > - 12 {
> > - 13   spin_lock(&rcu_gp_lock);
> > - 14   spin_unlock(&rcu_gp_lock);
> > - 15 }
> > -\end{verbbox}
> > -}
> > -\centering
> > -\theverbbox
> > +\begin{listing}[htbp]
> > +\input{CodeSamples/defer/rcu_lock@lock_unlock.fcv}\vspace*{-11pt}\fvset{firstnumber=last}
> > +\input{CodeSamples/defer/rcu_lock@synchronize.fcv}\fvset{firstnumber=auto}
> >  \caption{Lock-Based RCU Implementation}
> >  \label{lst:app:toyrcu:Lock-Based RCU Implementation}
> >  \end{listing}
> > --
> > 2.17.1
> >
> >
> 

Re: [PATCH 0/7] Collection of small fixes and updates

[Paul E. McKenney]

On Sun, Jul 21, 2019 at 08:59:50AM +0900, Akira Yokosawa wrote:
> Hi Paul,
> (Cc: Junchang, Elad)
> 
> I've got somewhat distracted and couldn't properly compose change logs
> of patches I collected in a work-in-progress branch.

No need to apologize, you might have noticed that I have been more
distracted from this project than I would have liked.  Good stuff,
thank you!

							Thanx, Paul

> Finally I managed to update the style guide to reflect enhancements in
> fcvextract.pl and amend the commit logs.
> 
> Patch #1 was the one presented to Junchang as an example to combine
> two code fragments in a code snippet.
> Patch #2 applies the new scheme to another fragment in rcu_nest.h,
> which was updated by Junchang.
> Patch #3 fixes type reported by Elad.
> Patch #4 updates FAQ-BUILD.txt for F29 and F30 users.
> Patch #5 removes remnant of quantum computing.
> Patch #6 applies the new scheme to another fragment in rcu.h, which
> was also updated by Junchang.
> Patch #7 is the update of style guide
> 
> Patches #1, #2, #3, and #6 are CC'd to Junchang or Elad.
> I don't think their Acks are musts in these cases, but would highly
> appreciate them.
> 
>         Thanks, Akira
> --
> Akira Yokosawa (7):
>   toyrcu: Convert Listing B.1 to new scheme
>   toyrcu: Extract Listing B.15 from rcu_nest.h
>   toolsoftrade: Fix typo
>   FAQ-BUILD: Update for recent Fedora releases
>   howto: Stop mentioning quantum computing
>   toyrcu: Extract Listing B.13 from rcu.h
>   styleguide: Update description of available options to \begin{snippet}
> 
>  CodeSamples/defer/rcu.h                 |  2 +
>  CodeSamples/defer/rcu_lock.c            |  2 +
>  CodeSamples/defer/rcu_lock.h            |  2 +
>  CodeSamples/defer/rcu_nest.h            |  2 +
>  FAQ-BUILD.txt                           |  9 +--
>  appendix/styleguide/samplecodesnippet.c |  2 +-
>  appendix/styleguide/styleguide.tex      | 76 +++++++++++++++----------
>  appendix/toyrcu/toyrcu.tex              | 50 ++--------------
>  howto/howto.tex                         |  2 +-
>  toolsoftrade/toolsoftrade.tex           |  2 +-
>  10 files changed, 66 insertions(+), 83 deletions(-)
> 
> -- 
> 2.17.1
> 

Re: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme

[Akira Yokosawa]

On Mon, 22 Jul 2019 05:34:07 -0700, Paul E. McKenney wrote:
> On Sun, Jul 21, 2019 at 08:07:11PM +0800, Junchang Wang wrote:
>> Hi Akira,
>>
>> Thanks for the patch. The new scheme worked great as a good example of
>> composing my commits. So,
>>
>> Acked-by: Junchang Wang <junchangwang@gmail.com>
> 
> Thank you both!  I have queued and pushed this series, with Junchang's
> ack on this patch.

Paul, could you also pick up Junchang's other acks on patches 2/7 and 6/7 ?

        Thanks, Akira

> 
> 							Thanx, Paul
> 
>> Thanks,
>> --Junchang
>>
>> On Sun, Jul 21, 2019 at 8:02 AM Akira Yokosawa <akiyks@gmail.com> wrote:
>>>
>>> From 245899f43fd007aa344180c0089515cd90f84db2 Mon Sep 17 00:00:00 2001
>>> From: Akira Yokosawa <akiyks@gmail.com>
>>> Date: Sat, 27 Apr 2019 21:04:40 +0900
>>> Subject: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme
>>>
>>> This commit was originally presented to Junchang as an example where
>>> code fragments extracted from two source files under CodeSamples/ are
>>> merged into a code snippet.
>>>
>>> Junchan employed this scheme in commits 686f3f3b721c ("rcu: Use
>>> READ_ONCE() and WRITE_ONCE() for shared variable rcu_gp_ctr"),
>>> a26c1625bb0d ("rcu_qs: Use READ_ONCE() AND WRITE_ONCE() for shared
>>> variable rcu_gp_ctr"), and b9696a4a456f ("rcu_nest: Update description
>>> of rcu_nest.[hc]").
>>>
>>> Extra vertical space needs to be canceled by the \vspace*{} command
>>> between the two \input{} commands.
>>> \fvset{firstnumber=last} is to continue line numbering.
>>> \fvset{firstnumber=auto} restores the default setting.
>>>
>>> Also tweak positioning option of the listing environment.
>>>
>>> Cc: Junchang Wang <junchangwang@gmail.com>
>>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>>> ---
>>>  CodeSamples/defer/rcu_lock.c |  2 ++
>>>  CodeSamples/defer/rcu_lock.h |  2 ++
>>>  appendix/toyrcu/toyrcu.tex   | 26 ++++----------------------
>>>  3 files changed, 8 insertions(+), 22 deletions(-)
>>>
>>> diff --git a/CodeSamples/defer/rcu_lock.c b/CodeSamples/defer/rcu_lock.c
>>> index 8d45ac89..08b87fbd 100644
>>> --- a/CodeSamples/defer/rcu_lock.c
>>> +++ b/CodeSamples/defer/rcu_lock.c
>>> @@ -20,12 +20,14 @@
>>>
>>>  #include "../api.h"
>>>  #include "rcu_lock.h"
>>> +//\begin{snippet}[labelbase=ln:defer:rcu_lock:synchronize,commandchars=\\\[\]]
>>>
>>>  void synchronize_rcu(void)
>>>  {
>>>         spin_lock(&rcu_gp_lock);
>>>         spin_unlock(&rcu_gp_lock);
>>>  }
>>> +//\end{snippet}
>>>
>>>  #ifdef TEST
>>>  #include "rcutorture.h"
>>> diff --git a/CodeSamples/defer/rcu_lock.h b/CodeSamples/defer/rcu_lock.h
>>> index 224ea0e4..bf6f9b3c 100644
>>> --- a/CodeSamples/defer/rcu_lock.h
>>> +++ b/CodeSamples/defer/rcu_lock.h
>>> @@ -26,6 +26,7 @@ static void rcu_init(void)
>>>  {
>>>  }
>>>
>>> +//\begin{snippet}[labelbase=ln:defer:rcu_lock:lock_unlock,commandchars=\\\[\]]
>>>  static void rcu_read_lock(void)
>>>  {
>>>         spin_lock(&rcu_gp_lock);
>>> @@ -35,5 +36,6 @@ static void rcu_read_unlock(void)
>>>  {
>>>         spin_unlock(&rcu_gp_lock);
>>>  }
>>> +//\end{snippet}
>>>
>>>  extern void synchronize_rcu(void);
>>> diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
>>> index 0e84b058..d876595b 100644
>>> --- a/appendix/toyrcu/toyrcu.tex
>>> +++ b/appendix/toyrcu/toyrcu.tex
>>> @@ -30,29 +30,11 @@ provides a summary and a list of desirable RCU properties.
>>>
>>>  \section{Lock-Based RCU}
>>>  \label{sec:app:toyrcu:Lock-Based RCU}
>>> +\NoIndentAfterThis
>>>
>>> -\begin{listing}[bp]
>>> -{ \scriptsize
>>> -\begin{verbbox}
>>> -  1 static void rcu_read_lock(void)
>>> -  2 {
>>> -  3   spin_lock(&rcu_gp_lock);
>>> -  4 }
>>> -  5
>>> -  6 static void rcu_read_unlock(void)
>>> -  7 {
>>> -  8   spin_unlock(&rcu_gp_lock);
>>> -  9 }
>>> - 10
>>> - 11 void synchronize_rcu(void)
>>> - 12 {
>>> - 13   spin_lock(&rcu_gp_lock);
>>> - 14   spin_unlock(&rcu_gp_lock);
>>> - 15 }
>>> -\end{verbbox}
>>> -}
>>> -\centering
>>> -\theverbbox
>>> +\begin{listing}[htbp]
>>> +\input{CodeSamples/defer/rcu_lock@lock_unlock.fcv}\vspace*{-11pt}\fvset{firstnumber=last}
>>> +\input{CodeSamples/defer/rcu_lock@synchronize.fcv}\fvset{firstnumber=auto}
>>>  \caption{Lock-Based RCU Implementation}
>>>  \label{lst:app:toyrcu:Lock-Based RCU Implementation}
>>>  \end{listing}
>>> --
>>> 2.17.1
>>>
>>>
>>
> 

Re: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme

[Paul E. McKenney]

On Tue, Jul 23, 2019 at 12:12:04AM +0900, Akira Yokosawa wrote:
> On Mon, 22 Jul 2019 05:34:07 -0700, Paul E. McKenney wrote:
> > On Sun, Jul 21, 2019 at 08:07:11PM +0800, Junchang Wang wrote:
> >> Hi Akira,
> >>
> >> Thanks for the patch. The new scheme worked great as a good example of
> >> composing my commits. So,
> >>
> >> Acked-by: Junchang Wang <junchangwang@gmail.com>
> > 
> > Thank you both!  I have queued and pushed this series, with Junchang's
> > ack on this patch.
> 
> Paul, could you also pick up Junchang's other acks on patches 2/7 and 6/7 ?

Ah, I didn't see Acked-by on those two.

Junchang, you are OK with my adding your Acked-by on those as well?

One labor-saving device you can use is something like this:

	For 1/7, 2/7, and 6/7:

	Acked-by: Your Name <your@email.address>

							Thanx, Paul

>         Thanks, Akira
> 
> > 
> > 							Thanx, Paul
> > 
> >> Thanks,
> >> --Junchang
> >>
> >> On Sun, Jul 21, 2019 at 8:02 AM Akira Yokosawa <akiyks@gmail.com> wrote:
> >>>
> >>> From 245899f43fd007aa344180c0089515cd90f84db2 Mon Sep 17 00:00:00 2001
> >>> From: Akira Yokosawa <akiyks@gmail.com>
> >>> Date: Sat, 27 Apr 2019 21:04:40 +0900
> >>> Subject: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme
> >>>
> >>> This commit was originally presented to Junchang as an example where
> >>> code fragments extracted from two source files under CodeSamples/ are
> >>> merged into a code snippet.
> >>>
> >>> Junchan employed this scheme in commits 686f3f3b721c ("rcu: Use
> >>> READ_ONCE() and WRITE_ONCE() for shared variable rcu_gp_ctr"),
> >>> a26c1625bb0d ("rcu_qs: Use READ_ONCE() AND WRITE_ONCE() for shared
> >>> variable rcu_gp_ctr"), and b9696a4a456f ("rcu_nest: Update description
> >>> of rcu_nest.[hc]").
> >>>
> >>> Extra vertical space needs to be canceled by the \vspace*{} command
> >>> between the two \input{} commands.
> >>> \fvset{firstnumber=last} is to continue line numbering.
> >>> \fvset{firstnumber=auto} restores the default setting.
> >>>
> >>> Also tweak positioning option of the listing environment.
> >>>
> >>> Cc: Junchang Wang <junchangwang@gmail.com>
> >>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> >>> ---
> >>>  CodeSamples/defer/rcu_lock.c |  2 ++
> >>>  CodeSamples/defer/rcu_lock.h |  2 ++
> >>>  appendix/toyrcu/toyrcu.tex   | 26 ++++----------------------
> >>>  3 files changed, 8 insertions(+), 22 deletions(-)
> >>>
> >>> diff --git a/CodeSamples/defer/rcu_lock.c b/CodeSamples/defer/rcu_lock.c
> >>> index 8d45ac89..08b87fbd 100644
> >>> --- a/CodeSamples/defer/rcu_lock.c
> >>> +++ b/CodeSamples/defer/rcu_lock.c
> >>> @@ -20,12 +20,14 @@
> >>>
> >>>  #include "../api.h"
> >>>  #include "rcu_lock.h"
> >>> +//\begin{snippet}[labelbase=ln:defer:rcu_lock:synchronize,commandchars=\\\[\]]
> >>>
> >>>  void synchronize_rcu(void)
> >>>  {
> >>>         spin_lock(&rcu_gp_lock);
> >>>         spin_unlock(&rcu_gp_lock);
> >>>  }
> >>> +//\end{snippet}
> >>>
> >>>  #ifdef TEST
> >>>  #include "rcutorture.h"
> >>> diff --git a/CodeSamples/defer/rcu_lock.h b/CodeSamples/defer/rcu_lock.h
> >>> index 224ea0e4..bf6f9b3c 100644
> >>> --- a/CodeSamples/defer/rcu_lock.h
> >>> +++ b/CodeSamples/defer/rcu_lock.h
> >>> @@ -26,6 +26,7 @@ static void rcu_init(void)
> >>>  {
> >>>  }
> >>>
> >>> +//\begin{snippet}[labelbase=ln:defer:rcu_lock:lock_unlock,commandchars=\\\[\]]
> >>>  static void rcu_read_lock(void)
> >>>  {
> >>>         spin_lock(&rcu_gp_lock);
> >>> @@ -35,5 +36,6 @@ static void rcu_read_unlock(void)
> >>>  {
> >>>         spin_unlock(&rcu_gp_lock);
> >>>  }
> >>> +//\end{snippet}
> >>>
> >>>  extern void synchronize_rcu(void);
> >>> diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
> >>> index 0e84b058..d876595b 100644
> >>> --- a/appendix/toyrcu/toyrcu.tex
> >>> +++ b/appendix/toyrcu/toyrcu.tex
> >>> @@ -30,29 +30,11 @@ provides a summary and a list of desirable RCU properties.
> >>>
> >>>  \section{Lock-Based RCU}
> >>>  \label{sec:app:toyrcu:Lock-Based RCU}
> >>> +\NoIndentAfterThis
> >>>
> >>> -\begin{listing}[bp]
> >>> -{ \scriptsize
> >>> -\begin{verbbox}
> >>> -  1 static void rcu_read_lock(void)
> >>> -  2 {
> >>> -  3   spin_lock(&rcu_gp_lock);
> >>> -  4 }
> >>> -  5
> >>> -  6 static void rcu_read_unlock(void)
> >>> -  7 {
> >>> -  8   spin_unlock(&rcu_gp_lock);
> >>> -  9 }
> >>> - 10
> >>> - 11 void synchronize_rcu(void)
> >>> - 12 {
> >>> - 13   spin_lock(&rcu_gp_lock);
> >>> - 14   spin_unlock(&rcu_gp_lock);
> >>> - 15 }
> >>> -\end{verbbox}
> >>> -}
> >>> -\centering
> >>> -\theverbbox
> >>> +\begin{listing}[htbp]
> >>> +\input{CodeSamples/defer/rcu_lock@lock_unlock.fcv}\vspace*{-11pt}\fvset{firstnumber=last}
> >>> +\input{CodeSamples/defer/rcu_lock@synchronize.fcv}\fvset{firstnumber=auto}
> >>>  \caption{Lock-Based RCU Implementation}
> >>>  \label{lst:app:toyrcu:Lock-Based RCU Implementation}
> >>>  \end{listing}
> >>> --
> >>> 2.17.1
> >>>
> >>>
> >>
> > 
> 

Re: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme

[Akira Yokosawa]

On 2019/07/23 1:28, Paul E. McKenney wrote:
> On Tue, Jul 23, 2019 at 12:12:04AM +0900, Akira Yokosawa wrote:
>> On Mon, 22 Jul 2019 05:34:07 -0700, Paul E. McKenney wrote:
>>> On Sun, Jul 21, 2019 at 08:07:11PM +0800, Junchang Wang wrote:
>>>> Hi Akira,
>>>>
>>>> Thanks for the patch. The new scheme worked great as a good example of
>>>> composing my commits. So,
>>>>
>>>> Acked-by: Junchang Wang <junchangwang@gmail.com>
>>>
>>> Thank you both!  I have queued and pushed this series, with Junchang's
>>> ack on this patch.
>>
>> Paul, could you also pick up Junchang's other acks on patches 2/7 and 6/7 ?
> 
> Ah, I didn't see Acked-by on those two.

Umm, I _thought_ I had seen them, but apparently I might have been daydreaming
or something :-)

Sorry for the noise.

        Thanks, Akira

> 
> Junchang, you are OK with my adding your Acked-by on those as well?
> 
> One labor-saving device you can use is something like this:
> 
> 	For 1/7, 2/7, and 6/7:
> 
> 	Acked-by: Your Name <your@email.address>
> 
> 							Thanx, Paul
> 
>>         Thanks, Akira
>>
>>>
>>> 							Thanx, Paul
>>>
>>>> Thanks,
>>>> --Junchang
>>>>
>>>> On Sun, Jul 21, 2019 at 8:02 AM Akira Yokosawa <akiyks@gmail.com> wrote:
>>>>>
>>>>> From 245899f43fd007aa344180c0089515cd90f84db2 Mon Sep 17 00:00:00 2001
>>>>> From: Akira Yokosawa <akiyks@gmail.com>
>>>>> Date: Sat, 27 Apr 2019 21:04:40 +0900
>>>>> Subject: [PATCH 1/7] toyrcu: Convert Listing B.1 to new scheme
>>>>>
>>>>> This commit was originally presented to Junchang as an example where
>>>>> code fragments extracted from two source files under CodeSamples/ are
>>>>> merged into a code snippet.
>>>>>
>>>>> Junchan employed this scheme in commits 686f3f3b721c ("rcu: Use
>>>>> READ_ONCE() and WRITE_ONCE() for shared variable rcu_gp_ctr"),
>>>>> a26c1625bb0d ("rcu_qs: Use READ_ONCE() AND WRITE_ONCE() for shared
>>>>> variable rcu_gp_ctr"), and b9696a4a456f ("rcu_nest: Update description
>>>>> of rcu_nest.[hc]").
>>>>>
>>>>> Extra vertical space needs to be canceled by the \vspace*{} command
>>>>> between the two \input{} commands.
>>>>> \fvset{firstnumber=last} is to continue line numbering.
>>>>> \fvset{firstnumber=auto} restores the default setting.
>>>>>
>>>>> Also tweak positioning option of the listing environment.
>>>>>
>>>>> Cc: Junchang Wang <junchangwang@gmail.com>
>>>>> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
>>>>> ---
>>>>>  CodeSamples/defer/rcu_lock.c |  2 ++
>>>>>  CodeSamples/defer/rcu_lock.h |  2 ++
>>>>>  appendix/toyrcu/toyrcu.tex   | 26 ++++----------------------
>>>>>  3 files changed, 8 insertions(+), 22 deletions(-)
>>>>>
>>>>> diff --git a/CodeSamples/defer/rcu_lock.c b/CodeSamples/defer/rcu_lock.c
>>>>> index 8d45ac89..08b87fbd 100644
>>>>> --- a/CodeSamples/defer/rcu_lock.c
>>>>> +++ b/CodeSamples/defer/rcu_lock.c
>>>>> @@ -20,12 +20,14 @@
>>>>>
>>>>>  #include "../api.h"
>>>>>  #include "rcu_lock.h"
>>>>> +//\begin{snippet}[labelbase=ln:defer:rcu_lock:synchronize,commandchars=\\\[\]]
>>>>>
>>>>>  void synchronize_rcu(void)
>>>>>  {
>>>>>         spin_lock(&rcu_gp_lock);
>>>>>         spin_unlock(&rcu_gp_lock);
>>>>>  }
>>>>> +//\end{snippet}
>>>>>
>>>>>  #ifdef TEST
>>>>>  #include "rcutorture.h"
>>>>> diff --git a/CodeSamples/defer/rcu_lock.h b/CodeSamples/defer/rcu_lock.h
>>>>> index 224ea0e4..bf6f9b3c 100644
>>>>> --- a/CodeSamples/defer/rcu_lock.h
>>>>> +++ b/CodeSamples/defer/rcu_lock.h
>>>>> @@ -26,6 +26,7 @@ static void rcu_init(void)
>>>>>  {
>>>>>  }
>>>>>
>>>>> +//\begin{snippet}[labelbase=ln:defer:rcu_lock:lock_unlock,commandchars=\\\[\]]
>>>>>  static void rcu_read_lock(void)
>>>>>  {
>>>>>         spin_lock(&rcu_gp_lock);
>>>>> @@ -35,5 +36,6 @@ static void rcu_read_unlock(void)
>>>>>  {
>>>>>         spin_unlock(&rcu_gp_lock);
>>>>>  }
>>>>> +//\end{snippet}
>>>>>
>>>>>  extern void synchronize_rcu(void);
>>>>> diff --git a/appendix/toyrcu/toyrcu.tex b/appendix/toyrcu/toyrcu.tex
>>>>> index 0e84b058..d876595b 100644
>>>>> --- a/appendix/toyrcu/toyrcu.tex
>>>>> +++ b/appendix/toyrcu/toyrcu.tex
>>>>> @@ -30,29 +30,11 @@ provides a summary and a list of desirable RCU properties.
>>>>>
>>>>>  \section{Lock-Based RCU}
>>>>>  \label{sec:app:toyrcu:Lock-Based RCU}
>>>>> +\NoIndentAfterThis
>>>>>
>>>>> -\begin{listing}[bp]
>>>>> -{ \scriptsize
>>>>> -\begin{verbbox}
>>>>> -  1 static void rcu_read_lock(void)
>>>>> -  2 {
>>>>> -  3   spin_lock(&rcu_gp_lock);
>>>>> -  4 }
>>>>> -  5
>>>>> -  6 static void rcu_read_unlock(void)
>>>>> -  7 {
>>>>> -  8   spin_unlock(&rcu_gp_lock);
>>>>> -  9 }
>>>>> - 10
>>>>> - 11 void synchronize_rcu(void)
>>>>> - 12 {
>>>>> - 13   spin_lock(&rcu_gp_lock);
>>>>> - 14   spin_unlock(&rcu_gp_lock);
>>>>> - 15 }
>>>>> -\end{verbbox}
>>>>> -}
>>>>> -\centering
>>>>> -\theverbbox
>>>>> +\begin{listing}[htbp]
>>>>> +\input{CodeSamples/defer/rcu_lock@lock_unlock.fcv}\vspace*{-11pt}\fvset{firstnumber=last}
>>>>> +\input{CodeSamples/defer/rcu_lock@synchronize.fcv}\fvset{firstnumber=auto}
>>>>>  \caption{Lock-Based RCU Implementation}
>>>>>  \label{lst:app:toyrcu:Lock-Based RCU Implementation}
>>>>>  \end{listing}
>>>>> --
>>>>> 2.17.1
>>>>>
>>>>>
>>>>
>>>
>>