Skip to contentSkip to conversation

howto: Reduce width of Listings 2.1 and 2.2

PATCH Applied Akira Yokosawa 2 participants 8 messages Jan 30, 2020 – Jan 31, 2020 Kbuild

lore
Share & tools
lore
#0 lore raw

cover howto: Reduce width of Listings 2.1 and 2.2

From dc553b44983b30584d0f1003a729885b8b7290f2 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Thu, 30 Jan 2020 21:13:04 +0900
Subject: [PATCH 0/6] howto: Reduce width of Listings 2.1 and 2.2

Hi Paul,

This patch set has quite a large diff stats despite the small changes in the resulting PDF.
What I am trying here is to enable (semi-) automatic line breaks in code snippets.
The "fvextra" package enhances the capability of fancyvrb. By specifying "breaklines" and "breakafter" options to the VerbatimL environment, snippets with a long line can be typeset as a plain "listing" environment.
I see that Listings 2.1 and 2.2 do not deserve the full width of the page and tried to apply the fvextra approach.

However, there were unfortunate name collisions of custom environments.
"fvextra" requires the "lineno" package, where "linelabel" and "lineref" are used as global variables.

So I need to rename the environments to "fcvlabel" and "fcvref". Patch 1/6 does those renames, hence the large diff stats.

Patch 2/6 adds checks to detect now erroneous uses of "linelabel" and "lineref".
Without this change, as they are defined as LaTeX variables by "lineno", such uses wouldn't be caught by LaTeX as errors, but would end up in undefined references.
The remaining warnings in the log file would be far from pin-point.

Patch 3/6 actually modifies Listings 2.1 and 2.2. At this point, the symbol representing carriagereturn in Listing 2.1 doesn't look good enough to me.
Patch 5/6 takes care of the symbol. It also adds comments to mention the "-jN" option of "make".

Patch 4/6 updates FAQ-BUILD.txt.

Patch 6/6 is an independent change to loosen the required version of "epigraph". It turned out that the combination of the up-to-date "epigraph" and the "nowidow" packages doesn't work properly on TeX Live 2015/Debian (Ubuntu Xenial). On a more recent TeX Live installation where the combination works, a suggestion to upgrade "epigraph" will be output after the build completes.

As this patch set touches Makefile, please test carefully before pushing out.
Especially, I'd like you to test Patch 2/6 and see if the error message, displayed when you use "linelabel" or "lineref" in place of "fcvlabel" or "fcvref", looks OK to you.

Thanks, Akira
--
Akira Yokosawa (6):
Rename environments 'linelabel' and 'lineref'
Makefile: Check 'linelabel' and 'lineref' used as environment
howto: Reduce width of Listings 2.1 and 2.2
FAQ-BUILD: Add 'fvextra' to the list of packages in item 10
howto: Tweak carriagereturn symbol at fvextra's auto line break Remove required version of 'epigraph'

 FAQ-BUILD.txt                                |  30 ++-
 Makefile                                     |  47 ++++
 SMPdesign/SMPdesign.tex                      |  12 +-
 SMPdesign/beyond.tex                         |  44 ++--
 SMPdesign/partexercises.tex                  |  32 +--
 advsync/advsync.tex                          |   8 +-
 advsync/rt.tex                               |  40 ++--
 appendix/questions/after.tex                 |   4 +-
 appendix/styleguide/samplecodesnippetfcv.tex |   4 +-
 appendix/styleguide/styleguide.tex           |  52 ++--
 appendix/toyrcu/toyrcu.tex                   | 128 +++++-----
 appendix/whymb/whymemorybarriers.tex         |  16 +-
 count/count.tex                              | 200 ++++++++--------
 datastruct/datastruct.tex                    |  80 +++----
 debugging/debugging.tex                      |  12 +-
 defer/defer.tex                              |  16 +-
 defer/hazptr.tex                             |  20 +-
 defer/rcuapi.tex                             |   8 +-
 defer/rcufundamental.tex                     |   4 +-
 defer/rcuintro.tex                           |   4 +-
 defer/rcuusage.tex                           |  52 ++--
 defer/refcnt.tex                             |  20 +-
 defer/seqlock.tex                            |  40 ++--
 formal/axiomatic.tex                         |  40 ++--
 formal/dyntickrcu.tex                        | 148 ++++++------
 formal/ppcmem.tex                            |  24 +-
 formal/spinhint.tex                          |  44 ++--
 future/formalregress.tex                     |   4 +-
 future/htm.tex                               |  28 +--
 howto/howto.tex                              |  57 ++---
 locking/locking-existence.tex                |  20 +-
 locking/locking.tex                          |  76 +++---
 memorder/memorder.tex                        | 240 +++++++++----------
 owned/owned.tex                              |  12 +-
 perfbook.tex                                 |   9 +-
 together/applyrcu.tex                        |  32 +--
 together/refcnt.tex                          |  32 +--
 toolsoftrade/toolsoftrade.tex                | 184 +++++++-------
 utilities/checkfcv.pl                        |   8 +-
 utilities/fcvextract.pl                      |  10 +-
 40 files changed, 956 insertions(+), 885 deletions(-)
Signature · 1 line
2.17.1
#1 lore raw

PATCH 1/6 Rename environments 'linelabel' and 'lineref'

From 25f6cd58afa619edfd088e4a935b10f7dddf450f Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Sat, 25 Jan 2020 15:56:47 +0900
Subject: [PATCH 1/6] Rename environments 'linelabel' and 'lineref'

It turns out that the "lineno" package has variables \linelabel and \lineref as its parameters.
The "fvextra" package, which enhances fancyvrb and enables (semi-) automatic line breaking in code snippets, requires the "lineno" package.

This commit renames our custom environments of the same name to "fcvlabel" and "fcvref" for us to be able to make use of fvextra.

---
 SMPdesign/SMPdesign.tex                      |  12 +-
 SMPdesign/beyond.tex                         |  44 ++--
 SMPdesign/partexercises.tex                  |  32 +--
 advsync/advsync.tex                          |   8 +-
 advsync/rt.tex                               |  40 ++--
 appendix/questions/after.tex                 |   4 +-
 appendix/styleguide/samplecodesnippetfcv.tex |   4 +-
 appendix/styleguide/styleguide.tex           |  52 ++--
 appendix/toyrcu/toyrcu.tex                   | 128 +++++-----
 appendix/whymb/whymemorybarriers.tex         |  16 +-
 count/count.tex                              | 200 ++++++++--------
 datastruct/datastruct.tex                    |  80 +++----
 debugging/debugging.tex                      |  12 +-
 defer/defer.tex                              |  16 +-
 defer/hazptr.tex                             |  20 +-
 defer/rcuapi.tex                             |   8 +-
 defer/rcufundamental.tex                     |   4 +-
 defer/rcuintro.tex                           |   4 +-
 defer/rcuusage.tex                           |  52 ++--
 defer/refcnt.tex                             |  20 +-
 defer/seqlock.tex                            |  40 ++--
 formal/axiomatic.tex                         |  40 ++--
 formal/dyntickrcu.tex                        | 148 ++++++------
 formal/ppcmem.tex                            |  24 +-
 formal/spinhint.tex                          |  44 ++--
 future/formalregress.tex                     |   4 +-
 future/htm.tex                               |  28 +--
 locking/locking-existence.tex                |  20 +-
 locking/locking.tex                          |  76 +++---
 memorder/memorder.tex                        | 240 +++++++++----------
 owned/owned.tex                              |  12 +-
 perfbook.tex                                 |   4 +-
 together/applyrcu.tex                        |  32 +--
 together/refcnt.tex                          |  32 +--
 toolsoftrade/toolsoftrade.tex                | 184 +++++++-------
 utilities/checkfcv.pl                        |   8 +-
 utilities/fcvextract.pl                      |  10 +-
 37 files changed, 851 insertions(+), 851 deletions(-)
SMPdesign/SMPdesign.tex +6 -6
index 5fdf2a21..3c1fc41a 100644
@@ -859,7 +859,7 @@ In this case, the simpler data-locking approach would be simpler
 and likely perform better.
 
 \begin{listing}[tb]
-\begin{linelabel}[ln:SMPdesign:Hierarchical-Locking Hash Table Search]
+\begin{fcvlabel}[ln:SMPdesign:Hierarchical-Locking Hash Table Search]
 \begin{VerbatimL}[commandchars=\\\[\]]
 struct hash_table
 {
@@ -901,7 +901,7 @@ int hash_search(struct hash_table *h, long key)
 	return 0;
 }
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{Hierarchical-Locking Hash Table Search}
 \label{lst:SMPdesign:Hierarchical-Locking Hash Table Search}
 \end{listing}
@@ -1020,7 +1020,7 @@ smaller than the number of non-\co{NULL} pointers.
 
 \subsubsection{Allocation Function}
 
-\begin{lineref}[ln:SMPdesign:smpalloc:alloc]
+\begin{fcvref}[ln:SMPdesign:smpalloc:alloc]
 The allocation function \co{memblock_alloc()} may be seen in
 Listing~\ref{lst:SMPdesign:Allocator-Cache Allocator Function}.
 Line~\lnref{pick} picks up the current thread's per-thread pool,
@@ -1039,7 +1039,7 @@ In either case, line~\lnref{chk:notempty} checks for the per-thread
 pool still being
 empty, and if not, \clnrefrange{rem:b}{rem:e} remove a block and return it.
 Otherwise, line~\lnref{ret:NULL} tells the sad tale of memory exhaustion.
-\end{lineref}
+\end{fcvref}
 
 \begin{listing}[tbp]
 \input{CodeSamples/SMPdesign/[email protected]}
@@ -1049,7 +1049,7 @@ Otherwise, line~\lnref{ret:NULL} tells the sad tale of memory exhaustion.
 
 \subsubsection{Free Function}
 
-\begin{lineref}[ln:SMPdesign:smpalloc:free]
+\begin{fcvref}[ln:SMPdesign:smpalloc:free]
 Listing~\ref{lst:SMPdesign:Allocator-Cache Free Function} shows
 the memory-block free function.
 Line~\lnref{get} gets a pointer to this thread's pool, and
@@ -1065,7 +1065,7 @@ value.
 
 In either case, line~\lnref{place} then places the newly freed block into the
 per-thread pool.
-\end{lineref}
+\end{fcvref}
 
 \begin{listing}[tbp]
 \input{CodeSamples/SMPdesign/[email protected]}
SMPdesign/beyond.tex +22 -22

145 lines not on this page · raw message

SMPdesign/partexercises.tex +16 -16
index 2b8822a9..9cebe6b7 100644
@@ -358,7 +358,7 @@ Listing~\ref{lst:SMPdesign:Lock-Based Parallel Double-Ended Queue Data Structure
 shows the corresponding C-language data structure, assuming an
 existing \co{struct deq} that provides a trivially locked
 double-ended-queue implementation.
-\begin{lineref}[ln:SMPdesign:lockhdeq:struct_pdeq]
+\begin{fcvref}[ln:SMPdesign:lockhdeq:struct_pdeq]
 This data structure contains the left-hand lock on line~\lnref{llock},
 the left-hand index on line~\lnref{lidx}, the right-hand lock on line~\lnref{rlock}
 (which is cache-aligned in the actual implementation),
@@ -366,7 +366,7 @@ the right-hand index on line~\lnref{ridx}, and, finally, the hashed array
 of simple lock-based double-ended queues on line~\lnref{bkt}.
 A high-performance implementation would of course use padding or special
 alignment directives to avoid false sharing.
-\end{lineref}
+\end{fcvref}
 
 \begin{listing}[tbp]
 \input{CodeSamples/SMPdesign/lockhdeq@pop_push.fcv}
@@ -383,7 +383,7 @@ shows the implementation of the enqueue and dequeue functions.\footnote{
 Discussion will focus on the left-hand operations, as the right-hand
 operations are trivially derived from them.
 
-\begin{lineref}[ln:SMPdesign:lockhdeq:pop_push:popl]
+\begin{fcvref}[ln:SMPdesign:lockhdeq:pop_push:popl]
 \Clnrefrange{b}{e} show \co{pdeq_pop_l()},
 which left\-/dequeues and returns
 an element if possible, returning \co{NULL} otherwise.
@@ -396,9 +396,9 @@ non-\co{NULL}, line~\lnref{record} records the new left-hand index.
 Either way, line~\lnref{rel} releases the lock, and,
 finally, line~\lnref{return} returns
 the element if there was one, or \co{NULL} otherwise.
-\end{lineref}
+\end{fcvref}
 
-\begin{lineref}[ln:SMPdesign:lockhdeq:pop_push:pushl]
+\begin{fcvref}[ln:SMPdesign:lockhdeq:pop_push:pushl]
 \Clnrefrange{b}{e} show \co{pdeq_push_l()},
 which left-enqueues the specified
 element.
@@ -410,7 +410,7 @@ onto the double-ended queue
 indexed by the left-hand index.
 Line~\lnref{update} then updates the left-hand index
 and line~\lnref{rel} releases the lock.
-\end{lineref}
+\end{fcvref}
 
 As noted earlier, the right-hand operations are completely analogous
 to their left-handed counterparts, so their analysis is left as an
@@ -487,7 +487,7 @@ and \co{pdeq_pop_r()} implementations separately.
 	(see Section~\ref{sec:SMPdesign:Dining Philosophers Problem}).
 } \QuickQuizEnd
 
-\begin{lineref}[ln:SMPdesign:locktdeq:pop_push:popl]
+\begin{fcvref}[ln:SMPdesign:locktdeq:pop_push:popl]
 The \co{pdeq_pop_l()} implementation is shown on
 \clnrefrange{b}{e}
 of the figure.
@@ -505,9 +505,9 @@ queue to the left-hand queue, line~\lnref{init:r} initializes
 the right-hand queue,
 and line~\lnref{rel:r} releases the right-hand lock.
 The element, if any, that was dequeued on line~\lnref{deq:lr} will be returned.
-\end{lineref}
+\end{fcvref}
 
-\begin{lineref}[ln:SMPdesign:locktdeq:pop_push:popr]
+\begin{fcvref}[ln:SMPdesign:locktdeq:pop_push:popr]
 The \co{pdeq_pop_r()} implementation is shown on \clnrefrange{b}{e}
 of the figure.
 As before, line~\lnref{acq:r1} acquires the right-hand lock
@@ -528,19 +528,19 @@ failed, line~\lnref{deq:rl} right-dequeues an element from the left-hand queue
 from the left-hand queue to the right-hand queue, and line~\lnref{init:l}
 initializes the left-hand queue.
 Either way, line~\lnref{rel:l} releases the left-hand lock.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	Why is it necessary to retry the right-dequeue operation
 	on line~\ref{ln:SMPdesign:locktdeq:pop_push:popr:deq:rr2} of
 	Listing~\ref{lst:SMPdesign:Compound Parallel Double-Ended Queue Implementation}?
 \QuickQuizAnswer{
-	\begin{lineref}[ln:SMPdesign:locktdeq:pop_push:popr]
+	\begin{fcvref}[ln:SMPdesign:locktdeq:pop_push:popr]
 	This retry is necessary because some other thread might have
 	enqueued an element between the time that this thread dropped
 	\co{d->rlock} on line~\lnref{rel:r1} and the time that it reacquired this
 	same lock on line~\lnref{acq:r2}.
-	\end{lineref}
+	\end{fcvref}
 } \QuickQuizEnd
 
 \QuickQuiz{}
@@ -558,7 +558,7 @@ Either way, line~\lnref{rel:l} releases the left-hand lock.
 	it is worthwhile) is left as an exercise for the reader.
 } \QuickQuizEnd
 
-\begin{lineref}[ln:SMPdesign:locktdeq:pop_push:pushl]
+\begin{fcvref}[ln:SMPdesign:locktdeq:pop_push:pushl]
 The \co{pdeq_push_l()} implementation is shown on
 \clnrefrange{b}{e} of
 Listing~\ref{lst:SMPdesign:Compound Parallel Double-Ended Queue Implementation}.
@@ -566,11 +566,11 @@ Line~\lnref{acq:l} acquires the left-hand spinlock,
 line~\lnref{que:l} left-enqueues the
 element onto the left-hand queue, and finally line~\lnref{rel:l} releases
 the lock.
-\end{lineref}
-\begin{lineref}[ln:SMPdesign:locktdeq:pop_push:pushr]
+\end{fcvref}
+\begin{fcvref}[ln:SMPdesign:locktdeq:pop_push:pushr]
 The \co{pdeq_push_r()} implementation (shown on \clnrefrange{b}{e})
 is quite similar.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	But in the case where data is flowing in only one direction,
advsync/advsync.tex +4 -4
index 7dda22ad..7d637d31 100644
@@ -165,7 +165,7 @@ Cute definitional tricks notwithstanding, this algorithm is probably
 the most heavily used NBS algorithm in the Linux kernel.
 
 \begin{listing}[tbp]
-\begin{linelabel}[ln:count:NBS Enqueue Algorithm]
+\begin{fcvlabel}[ln:count:NBS Enqueue Algorithm]
 \begin{VerbatimL}[commandchars=\\\[\]]
 static inline bool
 ___cds_wfcq_append(struct cds_wfcq_head *head,
@@ -189,12 +189,12 @@ _cds_wfcq_enqueue(struct cds_wfcq_head *head,
 	                          new_tail, new_tail);
 }
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{NBS Enqueue Algorithm}
 \label{lst:count:NBS Enqueue Algorithm}
 \end{listing}
 
-\begin{lineref}[ln:count:NBS Enqueue Algorithm]
+\begin{fcvref}[ln:count:NBS Enqueue Algorithm]
 Another common NBS algorithm is the atomic queue where elements are
 enqueued using an atomic exchange instruction~\cite{MagedMichael1993JPDC},
 followed by a store into the \co{->next} pointer of the new element's
@@ -220,7 +220,7 @@ dequeues are blocking.
 This algorithm is nevertheless heavily used in practice, in part because
 most production software is not required to tolerate arbitrary fail-stop
 errors.
-\end{lineref}
+\end{fcvref}
 
 \subsection{Applicability of NBS Benefits}
 \label{sec:advsync:Applicability of NBS Benefits}
advsync/rt.tex +20 -20
index a92b83d0..6a2f25c8 100644
@@ -1156,7 +1156,7 @@ Otherwise, long RCU read-side critical sections would result in
 excessive real-time latencies.
 
 \begin{listing}[tb]
-\begin{linelabel}[ln:advsync:Preemptible Linux-Kernel RCU]
+\begin{fcvlabel}[ln:advsync:Preemptible Linux-Kernel RCU]
 \begin{VerbatimL}[commandchars=\\\[\]]
 void __rcu_read_lock(void)			\lnlbl[lock:b]
 {
@@ -1181,7 +1181,7 @@ void __rcu_read_unlock(void)		        \lnlbl[unl:b]
 	}					\lnlbl[unl:els:e]
 }						\lnlbl[unl:e]
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{Preemptible Linux-Kernel RCU}
 \label{lst:advsync:Preemptible Linux-Kernel RCU}
 \end{listing}
@@ -1198,19 +1198,19 @@ while in one of those pre-existing critical sections have removed
 themselves from their lists.
 A simplified version of this implementation is shown in
 \cref{lst:advsync:Preemptible Linux-Kernel RCU}.
-\begin{lineref}[ln:advsync:Preemptible Linux-Kernel RCU]
+\begin{fcvref}[ln:advsync:Preemptible Linux-Kernel RCU]
 The \co{__rcu_read_lock()} function spans \clnrefrange{lock:b}{lock:e} and
 the \co{__rcu_read_unlock()} function spans \clnrefrange{unl:b}{unl:e}.
-\end{lineref}
+\end{fcvref}
 
-\begin{lineref}[ln:advsync:Preemptible Linux-Kernel RCU:lock]
+\begin{fcvref}[ln:advsync:Preemptible Linux-Kernel RCU:lock]
 \Clnref{inc} of \co{__rcu_read_lock()} increments a per-task count of the
 number of nested \co{rcu_read_lock()} calls, and
 \clnref{bar} prevents the compiler from reordering the subsequent code in the
 RCU read-side critical section to precede the \co{rcu_read_lock()}.
-\end{lineref}
+\end{fcvref}
 
-\begin{lineref}[ln:advsync:Preemptible Linux-Kernel RCU:unl]
+\begin{fcvref}[ln:advsync:Preemptible Linux-Kernel RCU:unl]
 \Clnref{chkn} of \co{__rcu_read_unlock()} checks to see if the nesting
 level count is one, in other words, if this corresponds to the outermost
 \co{rcu_read_unlock()} of a nested set.
@@ -1246,10 +1246,10 @@ real-time software~\cite{BjoernBrandenburgPhD,DipankarSarma2004OLSscalability}.
 Whether or not special handling is required, \clnref{bar3} prevents the compiler
 from reordering the check on \clnref{chks} with the zeroing of the nesting
 count on \clnref{zero}.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
-	\begin{lineref}[ln:advsync:Preemptible Linux-Kernel RCU:unl]
+	\begin{fcvref}[ln:advsync:Preemptible Linux-Kernel RCU:unl]
 	Suppose that preemption occurs just after the load from
 	\co{t->rcu_read_unlock_special.s} on \clnref{chks} of
 	\cref{lst:advsync:Preemptible Linux-Kernel RCU}.
@@ -1257,7 +1257,7 @@ count on \clnref{zero}.
 	\co{rcu_read_unlock_special()}, thus failing to remove itself
 	from the list of tasks blocking the current grace period,
 	in turn causing that grace period to extend indefinitely?
-	\end{lineref}
+	\end{fcvref}
 \QuickQuizAnswer{
 	That is a real problem, and it is solved in RCU's scheduler hook.
 	If that scheduler hook sees that the value of
@@ -1471,7 +1471,7 @@ OSADL runs long-term tests of systems, so referring to their
 website (\url{http://osadl.org/}) can be helpful.
 
 \begin{listing}[tb]
-\begin{linelabel}[ln:advsync:Locating Sources of OS Jitter]
+\begin{fcvlabel}[ln:advsync:Locating Sources of OS Jitter]
 \begin{VerbatimL}[commandchars=\\\[\]]
 cd /sys/kernel/debug/tracing
 echo 1 > max_graph_depth		\lnlbl[echo1]
@@ -1479,12 +1479,12 @@ echo function_graph > current_tracer
 # run workload
 cat per_cpu/cpuN/trace			\lnlbl[cat]
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{Locating Sources of OS Jitter}
 \label{lst:advsync:Locating Sources of OS Jitter}
 \end{listing}
 
-\begin{lineref}[ln:advsync:Locating Sources of OS Jitter]
+\begin{fcvref}[ln:advsync:Locating Sources of OS Jitter]
 Unfortunately, this list of OS-jitter sources can never be complete,
 as it will change with each new version of the kernel.
 This makes it necessary to be able to track down additional sources
@@ -1498,7 +1498,7 @@ number of the CPU in question, and the \co{1} on \clnref{echo1} may be
 increased
 to show additional levels of function call within the kernel.
 The resulting trace can help track down the source of the OS jitter.
-\end{lineref}
+\end{fcvref}
 
 As you can see, obtaining bare-metal performance when running
 CPU-bound real-time threads on a general-purpose OS such as Linux
@@ -1716,7 +1716,7 @@ We therefore need to schedule the fuel injection to within a time
 interval of about 100 microseconds.
 
 \begin{listing}[tb]
-\begin{linelabel}[ln:advsync:Timed-Wait Test Program]
+\begin{fcvlabel}[ln:advsync:Timed-Wait Test Program]
 \begin{VerbatimL}
 if (clock_gettime(CLOCK_REALTIME, &timestart) != 0) {
 	perror("clock_gettime 1");
@@ -1731,7 +1731,7 @@ if (clock_gettime(CLOCK_REALTIME, &timeend) != 0) {
 	exit(-1);
 }
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{Timed-Wait Test Program}
 \label{lst:advsync:Timed-Wait Test Program}
 \end{listing}
@@ -1799,7 +1799,7 @@ Otherwise, \co{cur_cal} points to a dynamically allocated
 structure providing the current calibration values.
 
 \begin{listing}[tb]
-\begin{linelabel}[ln:advsync:Real-Time Calibration Using RCU]
+\begin{fcvlabel}[ln:advsync:Real-Time Calibration Using RCU]
 \begin{VerbatimL}[commandchars=\\\[\]]
 struct calibration {
 	short a;
@@ -1837,19 +1837,19 @@ bool update_cal(short a, short b, short c)		\lnlbl[upd:b]
 	return true;
 }							\lnlbl[upd:e]
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{Real-Time Calibration Using RCU}
 \label{lst:advsync:Real-Time Calibration Using RCU}
 \end{listing}
 
-\begin{lineref}[ln:advsync:Real-Time Calibration Using RCU]
+\begin{fcvref}[ln:advsync:Real-Time Calibration Using RCU]
 \Cref{lst:advsync:Real-Time Calibration Using RCU}
 shows how RCU can be used to solve this problem.
 Lookups are deterministic, as shown in \co{calc_control()}
 on \clnrefrange{calc:b}{calc:e}, consistent with real-time requirements.
 Updates are more complex, as shown by \co{update_cal()}
 on \clnrefrange{upd:b}{upd:e}.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	Given that real-time systems are often used for safety-critical
appendix/questions/after.tex +2 -2
index c56621bd..2c6c2aac 100644
@@ -88,7 +88,7 @@ a large number exceeding 10 microseconds, and one exceeding even
 Please note that this CPU can potentially execute more than 100,000
 instructions in that time.
 
-\begin{lineref}[ln:api-pthreads:QAfter:time]
+\begin{fcvref}[ln:api-pthreads:QAfter:time]
 One possible reason is given by the following sequence of events:
 \begin{enumerate}
 \item	Consumer obtains timestamp
@@ -136,7 +136,7 @@ producer's timestamp.
 The segments of code in each box in this figure are termed
 ``critical sections''; only one such critical section may be executing
 at a given time.
-\end{lineref}
+\end{fcvref}
 
 \begin{figure}[htb]
 \centering
appendix/styleguide/samplecodesnippetfcv.tex +2 -2
index b47b7f59..99952e5a 100644
@@ -1,5 +1,5 @@
 \begin{listing}[tb]
-\begin{linelabel}[ln:base1]			%lnlbl~beg:linelabel^
+\begin{fcvlabel}[ln:base1]			%lnlbl~beg:fcvlabel^
 \begin{VerbatimL}[commandchars=\$\[\]]
 /*
  * Sample Code Snippet
@@ -11,7 +11,7 @@ int main(void)
 	return 0;			$lnlbl[return]
 }
 \end{VerbatimL}
-\end{linelabel}					%lnlbl~end:linelabel^
+\end{fcvlabel}					%lnlbl~end:fcvlabel^
 \caption{Sample Code Snippet}
 \label{lst:app:styleguide:Sample Code Snippet}
 \end{listing}
appendix/styleguide/styleguide.tex +26 -26

163 lines not on this page · raw message

appendix/toyrcu/toyrcu.tex +64 -64

440 lines not on this page · raw message

appendix/whymb/whymemorybarriers.tex +8 -8
index cc5b2648..b5449c91 100644
@@ -993,7 +993,7 @@ is owned by CPU~0 (MESI ``exclusive'' or ``modified'' state).
 Then suppose that CPU~0 executes \co{foo()} while CPU~1 executes
 function \co{bar()} in the following code fragment:
 
-\begin{linelabel}[ln:app:whymb:Breaking mb]
+\begin{fcvlabel}[ln:app:whymb:Breaking mb]
 \begin{VerbatimN}[fontsize=\footnotesize,samepage=true,commandchars=\\\[\]]
 void foo(void)
 {
@@ -1008,10 +1008,10 @@ void bar(void)
 	assert(a == 1);
 }
 \end{VerbatimN}
-\end{linelabel}
+\end{fcvlabel}
 
 Then the sequence of operations might be as follows:
-\begin{lineref}[ln:app:whymb:Breaking mb]
+\begin{fcvref}[ln:app:whymb:Breaking mb]
 \begin{enumerate}
 \item	CPU~0 executes \co{a = 1}.  The corresponding
 	cache line is read-only in
@@ -1045,7 +1045,7 @@ Then the sequence of operations might be as follows:
 	``invalidate'' message, and (tardily)
 	invalidates the cache line containing ``a'' from its own cache.
 \end{enumerate}
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	In step~1 of the first scenario in
@@ -1071,7 +1071,7 @@ and forces any subsequent load to wait until all marked entries
 have been applied to the CPU's cache.
 Therefore, we can add a memory barrier to function \co{bar} as follows:
 
-\begin{linelabel}[ln:app:whymb:Add mb]
+\begin{fcvlabel}[ln:app:whymb:Add mb]
 \begin{VerbatimN}[fontsize=\footnotesize,samepage=true,commandchars=\\\[\]]
 void foo(void)
 {
@@ -1087,7 +1087,7 @@ void bar(void)
 	assert(a == 1);
 }
 \end{VerbatimN}
-\end{linelabel}
+\end{fcvlabel}
 
 \QuickQuiz{}
 	Say what???
@@ -1134,7 +1134,7 @@ void bar(void)
 %
 } \QuickQuizEnd
 
-\begin{lineref}[ln:app:whymb:Add mb]
+\begin{fcvref}[ln:app:whymb:Add mb]
 With this change, the sequence of operations might be as follows:
 \begin{enumerate}
 \item	CPU~0 executes \co{a = 1}.  The corresponding
@@ -1175,7 +1175,7 @@ With this change, the sequence of operations might be as follows:
 \item	CPU~1 receives this cache line, which contains a value of 1 for
 	``a'', so that the assertion does not trigger.
 \end{enumerate}
-\end{lineref}
+\end{fcvref}
 
 With much passing of MESI messages, the CPUs arrive at the correct answer.
 This section illustrates why CPU designers must be extremely careful
count/count.tex +100 -100

707 lines not on this page · raw message

datastruct/datastruct.tex +40 -40

269 lines not on this page · raw message

debugging/debugging.tex +6 -6
index 8ee99aa8..286f6df7 100644
@@ -2274,7 +2274,7 @@ Similarly, interrupt-based interference can be detected via the
 \path{/proc/interrupts} file.
 
 \begin{listing}[tb]
-\begin{linelabel}[ln:debugging:Using getrusage() to Detect Context Switches]
+\begin{fcvlabel}[ln:debugging:Using getrusage() to Detect Context Switches]
 \begin{VerbatimL}
 #include <sys/time.h>
 #include <sys/resource.h>
@@ -2298,7 +2298,7 @@ int runtest(void)
 	        ru1.runivcsw == ru2.runivcsw);
 }
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{Using \tco{getrusage()} to Detect Context Switches}
 \label{lst:debugging:Using getrusage() to Detect Context Switches}
 \end{listing}
@@ -2395,14 +2395,14 @@ This script takes three optional arguments as follows:
 	which case the ``break'' will be ignored.)
 \end{description}
 
-\begin{lineref}[ln:debugging:datablows:whole]
+\begin{fcvref}[ln:debugging:datablows:whole]
 \Clnrefrange{param:b}{param:e} of
 Listing~\ref{lst:debugging:Statistical Elimination of Interference}
 set the default values for the parameters, and
 \clnrefrange{parse:b}{parse:e} parse
 any command-line overriding of these parameters.
-\end{lineref}
-\begin{lineref}[ln:debugging:datablows:whole:awk]
+\end{fcvref}
+\begin{fcvref}[ln:debugging:datablows:whole:awk]
 The \co{awk} invocation on line~\lnref{invoke} sets the values of the
 \co{divisor}, \co{relerr}, and \co{trendbreak} variables to their
 \co{sh} counterparts.
@@ -2444,7 +2444,7 @@ then line~\lnref{break} exits the loop: We have the full good set of data.
 
 \Clnrefrange{comp_stat:b}{comp_stat:e} then compute and print
 statistics.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	This approach is just plain weird!
defer/defer.tex +8 -8
index db8fe1fb..e972ddc1 100644
@@ -81,26 +81,26 @@ list to evaluate a number of read-mostly synchronization techniques.
 Listing~\ref{lst:defer:Sequential Pre-BSD Routing Table} (\path{route_seq.c})
 shows a simple single-threaded implementation corresponding to
 Figure~\ref{fig:defer:Pre-BSD Packet Routing List}.
-\begin{lineref}[ln:defer:route_seq:lookup_add_del:entry]
+\begin{fcvref}[ln:defer:route_seq:lookup_add_del:entry]
 \Clnrefrange{b}{e} define a \co{route_entry} structure and
 line~\lnref{header} defines
 the \co{route_list} header.
-\end{lineref}
-\begin{lineref}[ln:defer:route_seq:lookup_add_del:lookup]
+\end{fcvref}
+\begin{fcvref}[ln:defer:route_seq:lookup_add_del:lookup]
 \Clnrefrange{b}{e} define \co{route_lookup()}, which sequentially searches
 \co{route_list}, returning the corresponding \co{->iface}, or
 \co{ULONG_MAX} if there is no such route entry.
-\end{lineref}
-\begin{lineref}[ln:defer:route_seq:lookup_add_del:add]
+\end{fcvref}
+\begin{fcvref}[ln:defer:route_seq:lookup_add_del:add]
 \Clnrefrange{b}{e} define \co{route_add()}, which allocates a
 \co{route_entry} structure, initializes it, and adds it to the
 list, returning \co{-ENOMEM} in case of memory-allocation failure.
-\end{lineref}
-\begin{lineref}[ln:defer:route_seq:lookup_add_del:del]
+\end{fcvref}
+\begin{fcvref}[ln:defer:route_seq:lookup_add_del:del]
 Finally, \clnrefrange{b}{e} define \co{route_del()}, which removes and
 frees the specified \co{route_entry} structure if it exists,
 or returns \co{-ENOENT} otherwise.
-\end{lineref}
+\end{fcvref}
 
 This single-threaded implementation serves as a prototype for the various
 concurrent implementations in this chapter, and also as an estimate of
defer/hazptr.tex +10 -10
index 2579ec4f..2b946244 100644
@@ -31,7 +31,7 @@ may safely be freed.
 Of course, this means that hazard-pointer acquisition must be carried
 out quite carefully in order to avoid destructive races with concurrent
 deletion.
-\begin{lineref}[ln:defer:hazptr:record_clear]
+\begin{fcvref}[ln:defer:hazptr:record_clear]
 One implementation is shown in
 Listing~\ref{lst:defer:Hazard-Pointer Recording and Clearing},
 which shows \co{hp_try_record()} on \clnrefrange{htr:b}{htr:e},
@@ -114,7 +114,7 @@ The \co{hp_clear()} function is even more straightforward, with
 an \co{smp_mb()} to force full ordering between the caller's uses
 of the object protected by the hazard pointer and the setting of
 the hazard pointer to \co{NULL}.
-\end{lineref}
+\end{fcvref}
 
 \begin{listing}[tbp]
 \input{CodeSamples/defer/hazptr@scan_free.fcv}
@@ -122,7 +122,7 @@ the hazard pointer to \co{NULL}.
 \label{lst:defer:Hazard-Pointer Scanning and Freeing}
 \end{listing}
 
-\begin{lineref}[ln:defer:hazptr:scan_free:free]
+\begin{fcvref}[ln:defer:hazptr:scan_free:free]
 Once a hazard-pointer-protected object has been removed from its
 linked data structure, so that it is now inaccessible to future
 hazard-pointer readers, it is passed to \co{hazptr_free_later()},
@@ -135,9 +135,9 @@ and line~\lnref{count} counts the object in \co{rcount}.
 If line~\lnref{check} sees that a sufficiently large number of objects are now
 queued, line~\lnref{scan} invokes \co{hazptr_scan()} to attempt to
 free some of them.
-\end{lineref}
+\end{fcvref}
 
-\begin{lineref}[ln:defer:hazptr:scan_free:scan]
+\begin{fcvref}[ln:defer:hazptr:scan_free:scan]
 The \co{hazptr_scan()} function is shown on \clnrefrange{b}{e}
 of the listing.
 This function relies on a fixed maximum number of threads (\co{NR_THREADS})
@@ -172,7 +172,7 @@ determine that there is a hazard pointer
 protecting this object, \clnrefrange{back:b}{back:e}
 place it back onto \co{rlist}.
 Otherwise, line~\lnref{free} frees the object.
-\end{lineref}
+\end{fcvref}
 
 \begin{listing}[tbp]
 \input{CodeSamples/defer/[email protected]}
@@ -193,7 +193,7 @@ on
 page~\pageref{lst:defer:Sequential Pre-BSD Routing Table},
 so only differences will be discussed.
 
-\begin{lineref}[ln:defer:route_hazptr:lookup]
+\begin{fcvref}[ln:defer:route_hazptr:lookup]
 Starting with
 Listing~\ref{lst:defer:Hazard-Pointer Pre-BSD Routing Table Lookup},
 line~\lnref{hh} shows the \co{->hh} field used to queue objects pending
@@ -217,7 +217,7 @@ upon \co{hp_try_record()} failure.
 And such restarting is absolutely required for correctness.  To see this,
 consider a hazard-pointer-protected linked list containing elements~A,
 B, and~C that is subjected to the following sequence of events:
-\end{lineref}
+\end{fcvref}
 
 \begin{enumerate}
 \item	Thread~0 stores a hazard pointer to element~B
@@ -305,7 +305,7 @@ footprint.
 \label{lst:defer:Hazard-Pointer Pre-BSD Routing Table Add/Delete}
 \end{listing}
 
-\begin{lineref}[ln:defer:route_hazptr:add_del]
+\begin{fcvref}[ln:defer:route_hazptr:add_del]
 In
 Listing~\ref{lst:defer:Hazard-Pointer Pre-BSD Routing Table Add/Delete},
 line~\lnref{init_freed} initializes \co{->re_freed},
@@ -316,7 +316,7 @@ line~\lnref{free_later} passes that object to the
 is safe to do so.
 The spinlocks work the same as in
 Listing~\ref{lst:defer:Reference-Counted Pre-BSD Routing Table Add/Delete}.
-\end{lineref}
+\end{fcvref}
 
 \begin{figure}[tb]
 \centering
defer/rcuapi.tex +4 -4
index 12bfd9b6..8a9baebc 100644
@@ -730,7 +730,7 @@ a given node's fields from 5, 6, and 7 to 5, 2, and 3, respectively.
 
 The code implementing this atomic update is straightforward:
 
-\begin{linelabel}[ln:defer:Canonical RCU Replacement Example (2nd)]
+\begin{fcvlabel}[ln:defer:Canonical RCU Replacement Example (2nd)]
 \begin{VerbatimN}[samepage=true,commandchars=\\\[\],firstnumber=15]
 q = kmalloc(sizeof(*p), GFP_KERNEL);	\lnlbl[kmalloc]
 *q = *p;				\lnlbl[copy]
@@ -740,7 +740,7 @@ list_replace_rcu(&p->list, &q->list);	\lnlbl[replace]
 synchronize_rcu();			\lnlbl[sync_rcu]
 kfree(p);				\lnlbl[kfree]
 \end{VerbatimN}
-\end{linelabel}
+\end{fcvlabel}
 
 \begin{figure}[tbp]
 \centering
@@ -768,7 +768,7 @@ The following text describes how to replace the \co{5,6,7} element
 with \co{5,2,3} in such a way that any given reader sees one of these
 two values.
 
-\begin{lineref}[ln:defer:Canonical RCU Replacement Example (2nd)]
+\begin{fcvref}[ln:defer:Canonical RCU Replacement Example (2nd)]
 Line~\lnref{kmalloc} \co{kmalloc()}s a replacement element, as follows,
 resulting in the state as shown in the second row of
 Figure~\ref{fig:defer:RCU Replacement in Linked List}.
@@ -814,7 +814,7 @@ of the list, but with the new element in place of the old.
 After the \co{kfree()} on line~\lnref{kfree} completes, the list will
 appear as shown on the final row of
 Figure~\ref{fig:defer:RCU Replacement in Linked List}.
-\end{lineref}
+\end{fcvref}
 
 Despite the fact that RCU was named after the replacement case,
 the vast majority of RCU usage within the Linux kernel relies on
defer/rcufundamental.tex +2 -2
index d1067591..08d30cc0 100644
@@ -465,13 +465,13 @@ on page~\pageref{lst:defer:Insertion and Deletion With Concurrent Readers},
 suppose that each reader thread invokes \co{access_route()} exactly
 once during its lifetime, and that there is no other communication among
 reader and updater threads.
-\begin{lineref}[ln:defer:Insertion and Deletion With Concurrent Readers]
+\begin{fcvref}[ln:defer:Insertion and Deletion With Concurrent Readers]
 Then each invocation of \co{access_route()} can be ordered after the
 \co{ins_route()} invocation that produced the \co{route} structure
 accessed by \clnref{access_rp} of the listing in \co{access_route()}
 and ordered before any subsequent
 \co{ins_route()} or \co{del_route()} invocation.
-\end{lineref}
+\end{fcvref}
 
 In summary, maintaining multiple versions is exactly what enables the
 extremely low overheads of RCU readers, and as noted earlier, many
defer/rcuintro.tex +2 -2
index 57a65024..79e794df 100644
@@ -375,7 +375,7 @@ has executed a context switch, which in turn guarantees that
 all pre-existing reader threads have completed.
 
 \begin{listing}[tbp]
-\begin{linelabel}[ln:defer:Insertion and Deletion With Concurrent Readers]
+\begin{fcvlabel}[ln:defer:Insertion and Deletion With Concurrent Readers]
 \begin{VerbatimL}[commandchars=\\\[\]]
 struct route *gptr;
 
@@ -416,7 +416,7 @@ int del_route(void)
 	return !!old_rp;
 }
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{Insertion and Deletion With Concurrent Readers}
 \label{lst:defer:Insertion and Deletion With Concurrent Readers}
 \end{listing}
defer/rcuusage.tex +26 -26

166 lines not on this page · raw message

defer/refcnt.tex +10 -10
index ef54f44b..6c2061cc 100644
@@ -48,7 +48,7 @@ shown in
 Listing~\ref{lst:defer:Sequential Pre-BSD Routing Table},
 only the differences will be discussed.
 
-\begin{lineref}[ln:defer:route_refcnt:lookup:entry]
+\begin{fcvref}[ln:defer:route_refcnt:lookup:entry]
 Starting with
 Listing~\ref{lst:defer:Reference-Counted Pre-BSD Routing Table Lookup},
 line~\lnref{refcnt} adds the actual reference counter,
@@ -56,20 +56,20 @@ line~\lnref{freed} adds a \co{->re_freed}
 use-after-free check field,
 line~\lnref{routelock} adds the \co{routelock} that will
 be used to synchronize concurrent updates,
-\end{lineref}
-\begin{lineref}[ln:defer:route_refcnt:lookup:re_free]
+\end{fcvref}
+\begin{fcvref}[ln:defer:route_refcnt:lookup:re_free]
 and \clnrefrange{b}{e} add \co{re_free()}, which sets
 \co{->re_freed}, enabling \co{route_lookup()} to check for
 use-after-free bugs.
-\end{lineref}
-\begin{lineref}[ln:defer:route_refcnt:lookup:lookup]
+\end{fcvref}
+\begin{fcvref}[ln:defer:route_refcnt:lookup:lookup]
 In \co{route_lookup()} itself,
 \clnrefrange{relprev:b}{relprev:e} release the reference
 count of the prior element and free it if the count becomes zero,
 and \clnrefrange{acq:b}{acq:e} acquire a reference on the new element,
 with lines~\lnref{check_uaf}
 and~\lnref{abort} performing the use-after-free check.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	Why bother with a use-after-free check?
@@ -89,7 +89,7 @@ and~\lnref{abort} performing the use-after-free check.
 	of increasing the probability of finding bugs.
 } \QuickQuizEnd
 
-\begin{lineref}[ln:defer:route_refcnt:add_del]
+\begin{fcvref}[ln:defer:route_refcnt:add_del]
 In Listing~\ref{lst:defer:Reference-Counted Pre-BSD Routing Table Add/Delete},
 lines~\lnref{acq1}, \lnref{rel1}, \lnref{acq2}, \lnref{rel2},
 and~\lnref{rel3} introduce locking to synchronize
@@ -98,7 +98,7 @@ Line~\lnref{init:freed} initializes the \co{->re_freed} use-after-free-check fie
 and finally \clnrefrange{re_free:b}{re_free:e} invoke
 \co{re_free()} if the new value of
 the reference count is zero.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	Why doesn't \co{route_del()} in
@@ -215,7 +215,7 @@ One sequence of events leading to the use-after-free bug is as follows,
 given the list shown in
 Figure~\ref{fig:defer:Pre-BSD Packet Routing List}:
 
-\begin{lineref}[ln:defer:route_refcnt:lookup]
+\begin{fcvref}[ln:defer:route_refcnt:lookup]
 \begin{enumerate}
 \item	Thread~A looks up address~42, reaching
 	line~\lnref{lookup:check_NULL} of
@@ -236,7 +236,7 @@ Figure~\ref{fig:defer:Pre-BSD Packet Routing List}:
         so line~\lnref{lookup:abort} invokes
 	\co{abort()}.
 \end{enumerate}
-\end{lineref}
+\end{fcvref}
 
 The problem is that the reference count is located in the object
 to be protected, but that means that there is no protection during
defer/seqlock.tex +20 -20
index ab43013c..9cdc161b 100644
@@ -103,17 +103,17 @@ It is also used in pathname traversal to detect concurrent rename operations.
 A simple implementation of sequence locks is shown in
 Listing~\ref{lst:defer:Sequence-Locking Implementation}
 (\path{seqlock.h}).
-\begin{lineref}[ln:defer:seqlock:impl:typedef]
+\begin{fcvref}[ln:defer:seqlock:impl:typedef]
 The \co{seqlock_t} data structure is shown on
 \clnrefrange{b}{e}, and contains
 the sequence number along with a lock to serialize writers.
-\end{lineref}
-\begin{lineref}[ln:defer:seqlock:impl:init]
+\end{fcvref}
+\begin{fcvref}[ln:defer:seqlock:impl:init]
 \Clnrefrange{b}{e} show \co{seqlock_init()}, which, as the name indicates,
 initializes a \co{seqlock_t}.
-\end{lineref}
+\end{fcvref}
 
-\begin{lineref}[ln:defer:seqlock:impl:read_seqbegin]
+\begin{fcvref}[ln:defer:seqlock:impl:read_seqbegin]
 \Clnrefrange{b}{e} show \co{read_seqbegin()}, which begins a sequence-lock
 read-side critical section.
 Line~\lnref{fetch} takes a snapshot of the sequence counter, and
@@ -122,7 +122,7 @@ this snapshot operation before the caller's critical section.
 Finally, line~\lnref{ret} returns the value of the snapshot (with the least-significant
 bit cleared), which the caller
 will pass to a later call to \co{read_seqretry()}.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	Why not have \co{read_seqbegin()} in
@@ -139,7 +139,7 @@ will pass to a later call to \co{read_seqretry()}.
 	check internal to \co{read_seqbegin()} might be preferable.
 } \QuickQuizEnd
 
-\begin{lineref}[ln:defer:seqlock:impl:read_seqretry]
+\begin{fcvref}[ln:defer:seqlock:impl:read_seqretry]
 \Clnrefrange{b}{e} show \co{read_seqretry()}, which returns true if there
 was at least one writer since the time of the corresponding
 call to \co{read_seqbegin()}.
@@ -148,7 +148,7 @@ fetch of the new snapshot of the sequence counter.
 Finally, line~\lnref{ret} checks whether the sequence counter has changed,
 in other words, whether there has been at least one writer, and returns
 true if so.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	Why is the \co{smp_mb()} on
@@ -170,7 +170,7 @@ true if so.
 \QuickQuizAnswer{
 	In older versions of the Linux kernel, no.
 
-	\begin{lineref}[ln:defer:seqlock:impl]
+	\begin{fcvref}[ln:defer:seqlock:impl]
 	In very new versions of the Linux kernel,
         line~\lnref{read_seqbegin:fetch} could use
 	\co{smp_load_acquire()} instead of \co{READ_ONCE()}, which
@@ -186,7 +186,7 @@ smp_store_release(&slp->seq, READ_ONCE(slp->seq) + 1);
 
 	This would allow the \co{smp_mb()} on
 	line~\lnref{write_sequnlock:mb} to be dropped.
-	\end{lineref}
+	\end{fcvref}
 } \QuickQuizEnd
 
 \QuickQuiz{}
@@ -200,16 +200,16 @@ smp_store_release(&slp->seq, READ_ONCE(slp->seq) + 1);
 	situation, in which case, go wild with the sequence-locking updates!
 } \QuickQuizEnd
 
-\begin{lineref}[ln:defer:seqlock:impl:write_seqlock]
+\begin{fcvref}[ln:defer:seqlock:impl:write_seqlock]
 \Clnrefrange{b}{e} show \co{write_seqlock()}, which simply acquires the lock,
 increments the sequence number, and executes a memory barrier to ensure
 that this increment is ordered before the caller's critical section.
-\end{lineref}
-\begin{lineref}[ln:defer:seqlock:impl:write_sequnlock]
+\end{fcvref}
+\begin{fcvref}[ln:defer:seqlock:impl:write_sequnlock]
 \Clnrefrange{b}{e} show \co{write_sequnlock()}, which executes a memory barrier
 to ensure that the caller's critical section is ordered before the
 increment of the sequence number on line~\lnref{inc}, then releases the lock.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
 	What if something else serializes writers, so that the lock
@@ -285,21 +285,21 @@ shows \co{route_add()} and \co{route_del()} (\path{route_seqlock.c}).
 This implementation is once again similar to its counterparts in earlier
 sections, so only the differences will be highlighted.
 
-\begin{lineref}[ln:defer:route_seqlock:lookup]
+\begin{fcvref}[ln:defer:route_seqlock:lookup]
 In
 Listing~\ref{lst:defer:Sequence-Locked Pre-BSD Routing Table Lookup},
 line~\lnref{struct:re_freed} adds \co{->re_freed}, which is checked on
 lines~\lnref{lookup:chk_freed} and~\lnref{lookup:abort}.
 Line~\lnref{struct:sl} adds a sequence lock, which is used by \co{route_lookup()}
-\end{lineref}
-\begin{lineref}[ln:defer:route_seqlock:lookup:lookup]
+\end{fcvref}
+\begin{fcvref}[ln:defer:route_seqlock:lookup:lookup]
 on lines~\lnref{r_sqbegin}, \lnref{r_sqretry1}, and~\lnref{r_sqretry2},
 with lines~\lnref{goto_retry1} and~\lnref{goto_retry2} branching back to
 the \co{retry} label on line~\lnref{retry}.
 The effect is to retry any lookup that runs concurrently with an update.
-\end{lineref}
+\end{fcvref}
 
-\begin{lineref}[ln:defer:route_seqlock:add_del]
+\begin{fcvref}[ln:defer:route_seqlock:add_del]
 In
 Listing~\ref{lst:defer:Sequence-Locked Pre-BSD Routing Table Add/Delete},
 lines~\lnref{add:w_sqlock}, \lnref{add:w_squnlock}, \lnref{del:w_sqlock},
@@ -307,7 +307,7 @@ lines~\lnref{add:w_sqlock}, \lnref{add:w_squnlock}, \lnref{del:w_sqlock},
 acquire and release the sequence lock,
 while lines~\lnref{add:clr_freed} and~\lnref{del:set_freed} handle \co{->re_freed}.
 This implementation is therefore quite straightforward.
-\end{lineref}
+\end{fcvref}
 
 \begin{figure}[tb]
 \centering
formal/axiomatic.tex +20 -20
index 368e257f..10bb33e9 100644
@@ -10,7 +10,7 @@
 	{\emph{George Santayana}}
 
 \begin{listing}[tb]
-\begin{linelabel}[ln:formal:IRIW Litmus Test]
+\begin{fcvlabel}[ln:formal:IRIW Litmus Test]
 \begin{VerbatimL}[commandchars=\%\@\$]
 PPC IRIW.litmus
 ""
@@ -29,7 +29,7 @@ stw r1,0(r2) | stw r1,0(r4) | lwz r3,0(r2) | lwz r3,0(r4) ;
 exists
 (2:r3=1 /\ 2:r5=0 /\ 3:r3=1 /\ 3:r5=0)
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{IRIW Litmus Test}
 \label{lst:formal:IRIW Litmus Test}
 \end{listing}
@@ -76,7 +76,7 @@ same litmus tests as PPCMEM, including the IRIW litmus test shown in
 Listing~\ref{lst:formal:IRIW Litmus Test}.
 
 \begin{listing}[tb]
-\begin{linelabel}[ln:formal:Expanded IRIW Litmus Test]
+\begin{fcvlabel}[ln:formal:Expanded IRIW Litmus Test]
 \begin{VerbatimL}[commandchars=\%\@\$]
 PPC IRIW5.litmus
 ""
@@ -102,7 +102,7 @@ stw r1,0(r2) | stw r1,0(r4) |              |              ;
 exists
 (2:r3=1 /\ 2:r5=0 /\ 3:r3=1 /\ 3:r5=0)
 \end{VerbatimL}
-\end{linelabel}
+\end{fcvlabel}
 \caption{Expanded IRIW Litmus Test}
 \label{lst:formal:Expanded IRIW Litmus Test}
 \end{listing}
@@ -254,7 +254,7 @@ The next section looks at RCU.
 \subsection{Axiomatic Approaches and RCU}
 \label{sec:formal:Axiomatic Approaches and RCU}
 
-\begin{lineref}[ln:formal:C-RCU-remove:whole]
+\begin{fcvref}[ln:formal:C-RCU-remove:whole]
 Axiomatic approaches can also analyze litmus tests involving
 RCU~\cite{Alglave:2018:FSC:3173162.3177156}.
 To that end,
@@ -296,7 +296,7 @@ as expected.
 Also as expected, removing line~\lnref{sync} results in \co{P0()}
 accessing a freed element, as indicated by the \co{Sometimes} in
 the \co{herd} output.
-\end{lineref}
+\end{fcvref}
 
 \begin{listing}[tb]
 \input{CodeSamples/formal/herd/[email protected]}
@@ -304,7 +304,7 @@ the \co{herd} output.
 \label{lst:formal:Complex RCU Litmus Test}
 \end{listing}
 
-\begin{lineref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
+\begin{fcvref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
 A litmus test for a more complex example proposed by
 Roman Penyaev~\cite{RomanPenyaev2018rrRCU} is shown in
 Listing~\ref{lst:formal:Complex RCU Litmus Test}
@@ -373,19 +373,19 @@ In either case, line~\lnref{updfree} emulates \co{free()} by storing
 zero to \co{x}.
 
 \QuickQuiz{}
-	\begin{lineref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
+	\begin{fcvref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
 	In Listing~\ref{lst:formal:Complex RCU Litmus Test},
 	why couldn't a reader fetch \co{c} just before \co{P1()}
 	zeroed it on line~\lnref{updinitcache}, and then later
 	store this same value back into \co{c} just after it was
 	zeroed, thus defeating the zeroing operation?
-	\end{lineref}
+	\end{fcvref}
 \QuickQuizAnswer{
-	\begin{lineref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
+	\begin{fcvref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
 	Because the reader advances to the next element on
 	line~\lnref{rdnext}, thus avoiding storing a pointer to the
 	same element as was fetched.
-	\end{lineref}
+	\end{fcvref}
 } \QuickQuizEnd
 
 The output of the \co{herd} tool when running this litmus test features
@@ -394,36 +394,36 @@ as expected.
 Also as expected, removing either \co{synchronize_rcu()} results
 in \co{P1()} accessing a freed element, as indicated by \co{Sometimes}
 in the \co{herd} output.
-\end{lineref}
+\end{fcvref}
 
 \QuickQuiz{}
-	\begin{lineref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
+	\begin{fcvref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
 	In Listing~\ref{lst:formal:Complex RCU Litmus Test},
 	why not have just one call to \co{synchronize_rcu()}
 	immediately before line~\lnref{updfree}?
-	\end{lineref}
+	\end{fcvref}
 \QuickQuizAnswer{
-	\begin{lineref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
+	\begin{fcvref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
 	Because this results in \co{P0()} accessing a freed element.
 	But don't take my word for this, try it out in \co{herd}!
-	\end{lineref}
+	\end{fcvref}
 } \QuickQuizEnd
 
 \QuickQuiz{}
-	\begin{lineref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
+	\begin{fcvref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
 	Also in Listing~\ref{lst:formal:Complex RCU Litmus Test},
 	can't line~\lnref{updfree} be \co{WRITE_ONCE()} instead
 	of \co{smp_store_release()}?
-	\end{lineref}
+	\end{fcvref}
 \QuickQuizAnswer{
-	\begin{lineref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
+	\begin{fcvref}[ln:formal:C-RomanPenyaev-list-rcu-rr:whole]
 	That is an excellent question.
 	As of late 2018, the answer is ``no one knows''.
 	Much depends on the semantics of ARMv8's conditional-move
 	instruction.
 	While awaiting clarity on these semantics, \co{smp_store_release()}
 	is the safe choice.
-	\end{lineref}
+	\end{fcvref}
 } \QuickQuizEnd
 
 These sections have shown how axiomatic approaches can successfully
formal/dyntickrcu.tex +74 -74

182 lines not on this page · raw message

formal/ppcmem.tex +12 -12
index 722bc4d1..184cdd0d 100644

Lines of this file are not shown. View the raw message.

formal/spinhint.tex +22 -22

44 lines not on this page · raw message

future/formalregress.tex +2 -2
index 8a4f3d2f..9bfcdd2d 100644

Lines of this file are not shown. View the raw message.

future/htm.tex +14 -14
index 73a931fa..43fc5581 100644

Lines of this file are not shown. View the raw message.

locking/locking-existence.tex +10 -10
index e9a57cdc..c075ee8d 100644

Lines of this file are not shown. View the raw message.

locking/locking.tex +38 -38

76 lines not on this page · raw message

memorder/memorder.tex +120 -120

240 lines not on this page · raw message

owned/owned.tex +6 -6
index 14257c60..ed0ec4f6 100644

Lines of this file are not shown. View the raw message.

perfbook.tex +2 -2
index 7799228d..757620ec 100644

Lines of this file are not shown. View the raw message.

together/applyrcu.tex +16 -16
index 24f611c7..4dfa4045 100644

Lines of this file are not shown. View the raw message.

together/refcnt.tex +16 -16
index 9fdc5b93..f94ecbb4 100644

Lines of this file are not shown. View the raw message.

toolsoftrade/toolsoftrade.tex +92 -92

184 lines not on this page · raw message

utilities/checkfcv.pl +4 -4
index 7a0a92b2..2f99d1cb 100755

Lines of this file are not shown. View the raw message.

utilities/fcvextract.pl +5 -5
index 04e3b222..97608fa6 100755

Lines of this file are not shown. View the raw message.

The rest of this diff is not shown. View the raw message.

Signature · 1 line
2.17.1

Part of the diff is not shown here. View the raw message.

#2 lore raw

PATCH 2/6 Makefile: Check 'linelabel' and 'lineref' used as environment

In reply to Akira Yokosawa

From 1701f75c55109e3d609a4a07b645610fccbff800 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Tue, 28 Jan 2020 00:36:27 +0900
Subject: [PATCH 2/6] Makefile: Check 'linelabel' and 'lineref' used as environment

Although linelabel and lineref are defined by lineno package, pdflatex won't detect error if they are used as environments. This commit adds checks to detect \begin{lineref}/\end{lineref}/ \begin{linelabel}/\end{lineref}.

---
 Makefile | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)
Makefile +26 -0
index 06226d63..3dbd5d53 100644
@@ -119,6 +119,16 @@ ifdef A2PING
     endif
   endif
 endif
+
+LINE_ENV_IGNORE := Makefile perfbook_flat.tex $(LATEXGENERATED))
+# following variables are intentionally defined using "="
+LINELABEL_ENV_BEGIN = $(patsubst ./%,%,$(shell grep -R -l -F '\begin{linelabel}' .))
+LINELABEL_ENV_END   = $(patsubst ./%,%,$(shell grep -R -l -F '\end{linelabel}' .))
+LINEREF_ENV_BEGIN   = $(patsubst ./%,%,$(shell grep -R -l -F '\begin{lineref}' .))
+LINEREF_ENV_END     = $(patsubst ./%,%,$(shell grep -R -l -F '\end{lineref}' .))
+LINELABEL_ENV = $(filter-out $(LINE_ENV_IGNORE),$(sort $(LINELABEL_ENV_BEGIN) $(LINELABEL_ENV_END)))
+LINEREF_ENV   = $(filter-out $(LINE_ENV_IGNORE),$(sort $(LINEREF_ENV_BEGIN) $(LINEREF_ENV_END)))
+
 SOURCES_OF_SNIPPET_ALL := $(shell grep -R -l -F '\begin{snippet}' CodeSamples)
 SOURCES_OF_LITMUS      := $(shell grep -R -l -F '\begin[snippet]' CodeSamples)
 SOURCES_OF_LTMS        := $(patsubst %.litmus,%.ltms,$(SOURCES_OF_LITMUS))
@@ -174,6 +184,22 @@ perfbook_flat.tex: autodate.tex $(PDFTARGETS_OF_EPS) $(PDFTARGETS_OF_SVG) $(FCVS
 ifndef LATEXPAND
 	$(error --> $@: latexpand not found. Please install it)
 endif
+	@if [ ! -z "$(LINELABEL_ENV)" -a "$(LINELABEL_ENV)" != " " ]; then \
+		echo "'linelabel' used as environment in $(LINELABEL_ENV)." ; \
+		echo "Use 'fcvlabel' instead." ; \
+		echo "------" ; \
+		grep -n -B 2 -A 2 -F 'linelabel' $(LINELABEL_ENV) ; \
+		echo "------" ; \
+		exit 1 ; \
+	fi
+	@if [ ! -z "$(LINEREF_ENV)" -a "$(LINEREF_ENV)" != " " ]; then \
+		echo "'lineref' used as environment in $(LINEREF_ENV)." ; \
+		echo "Use 'fcvref' instead." ; \
+		echo "------" ; \
+		grep -n -B 2 -A 2 -F 'lineref' $(LINEREF_ENV) ; \
+		echo "------" ; \
+		exit 1 ; \
+	fi
 	echo > qqz.tex
 	echo > contrib.tex
 	echo > origpub.tex
Signature · 1 line
2.17.1
#3 lore raw

PATCH 3/6 howto: Reduce width of Listings 2.1 and 2.2

In reply to Akira Yokosawa

From 2532ab50cc7ca8518e8faa790c46588ea6db11a3 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Sat, 25 Jan 2020 16:07:43 +0900
Subject: [PATCH 3/6] howto: Reduce width of Listings 2.1 and 2.2

As wide floats are hard to adjust their placement, reduce the width of these listings by using the "breaklines" and "breakafter" options enabled by the "fvextra" package.

Also move the floats to the recommended positions of next to the paragraphs they are called out.

---
 howto/howto.tex | 54 ++++++++++++++++++++++++-------------------------
 perfbook.tex    |  1 +
 2 files changed, 28 insertions(+), 27 deletions(-)
howto/howto.tex +27 -27
index 9d732692..de26a113 100644
@@ -381,33 +381,6 @@ Other types of systems have well-known ways of locating files by filename.
 \epigraph{If you become a teacher, by your pupils you'll be taught.}
 	 {\emph{Oscar Hammerstein II}}
 
-\begin{listing*}[tbp]
-\begin{VerbatimL}
-git clone git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git
-cd perfbook
-# You may need to install a font here. See item 1 in FAQ.txt.
-make
-evince perfbook.pdf & # Two-column version
-make perfbook-1c.pdf
-evince perfbook-1c.pdf & # One-column version for e-readers
-\end{VerbatimL}
-\caption{Creating an Up-To-Date PDF}
-\label{lst:howto:Creating a Up-To-Date PDF}
-\end{listing*}
-
-\begin{listing*}[tbp]
-\begin{VerbatimL}
-git remote update
-git checkout origin/master
-make
-evince perfbook.pdf & # Two-column version
-make perfbook-1c.pdf
-evince perfbook-1c.pdf & # One-column version for e-readers
-\end{VerbatimL}
-\caption{Generating an Updated PDF}
-\label{lst:howto:Generating an Updated PDF}
-\end{listing*}
-
 As the cover says, the editor is one Paul E.~McKenney.
 However, the editor does accept contributions via the
 \href{mailto:[email protected]}
@@ -426,6 +399,20 @@ Other packages may be required, depending on the distribution you use.
 The required list of packages for a few popular distributions is listed
 in the file \path{FAQ-BUILD.txt} in the \LaTeX{} source to the book.
 
+\begin{listing}[tbp]
+\begin{VerbatimL}[breaklines=true,breakafter=/,numbers=none,xleftmargin=0pt]
+git clone git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git
+cd perfbook
+# You may need to install a font. See item 1 in FAQ.txt.
+make
+evince perfbook.pdf & # Two-column version
+make perfbook-1c.pdf
+evince perfbook-1c.pdf & # One-column version for e-readers
+\end{VerbatimL}
+\caption{Creating an Up-To-Date PDF}
+\label{lst:howto:Creating a Up-To-Date PDF}
+\end{listing}
+
 To create and display a current \LaTeX{} source tree of this book,
 use the list of Linux commands shown in
 Listing~\ref{lst:howto:Creating a Up-To-Date PDF}.
@@ -441,6 +428,19 @@ must be run within the \path{perfbook} directory created by the commands
 shown in
 Listing~\ref{lst:howto:Creating a Up-To-Date PDF}.
 
+\begin{listing}[tbp]
+\begin{VerbatimL}[numbers=none,xleftmargin=0pt]
+git remote update
+git checkout origin/master
+make
+evince perfbook.pdf & # Two-column version
+make perfbook-1c.pdf
+evince perfbook-1c.pdf & # One-column version for e-readers
+\end{VerbatimL}
+\caption{Generating an Updated PDF}
+\label{lst:howto:Generating an Updated PDF}
+\end{listing}
+
 PDFs of this book are sporadically posted at
 \url{http://kernel.org/pub/linux/kernel/people/paulmck/perfbook/perfbook.html}
 and at
perfbook.tex +1 -0
index 757620ec..51e1f5e5 100644
@@ -54,6 +54,7 @@
 \usepackage{gensymb} % symbols for both text and math modes such as \degree and \micro
 \usepackage{verbatimbox}[2014/01/30] % for centering verbatim listing in figure environment
 \usepackage{fancyvrb}
+\usepackage{fvextra}[2016/09/02]
 \usepackage[bottom]{footmisc} % place footnotes under floating figures/tables
 \usepackage{tabularx}
 \usepackage[hyphens]{url}
Signature · 1 line
2.17.1
#4 lore raw

PATCH 4/6 FAQ-BUILD: Add 'fvextra' to the list of packages in item 10

In reply to Akira Yokosawa

From 02048d49fdfaa3a25fef817fa64bdac7dfafd752 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Sat, 25 Jan 2020 16:08:31 +0900
Subject: [PATCH 4/6] FAQ-BUILD: Add 'fvextra' to the list of packages in item 10

---
 FAQ-BUILD.txt | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)
FAQ-BUILD.txt +5 -3
index 27780759..98cfb57b 100644
@@ -178,13 +178,14 @@
 		On upstream TeX Live (assuming user mode installation):
 			tlmgr install newtx
 
-10.	Building perfbook fails with a warning of buggy cleveref/listings
-	or version mismatch of titlesec/draftwatermark/epigraph.
-	What can I do?
+10.	Building perfbook fails with a warning of buggy cleveref/listings,
+	version mismatch of titlesec/draftwatermark/epigraph/fvextra, or
+	missing fvextra. What can I do?
 
 	A.	They are known issues on Ubuntu Xenial (titlesec),
 		Ubuntu Bionic (cleveref), TeX Live 2014/2015 (listings),
 		TeX Live releases prior to 2015 (draftwatermark),
+		TeX Live releases prior to 2017 (fvextra),
 		and TeX Live releases prior to 2020 (epigraph).
 		This answer assumes Ubuntu, but it should work on other
 		distros.
@@ -195,6 +196,7 @@
 		http://mirrors.ctan.org/macros/latex/contrib/listings.zip
 		http://mirrors.ctan.org/macros/latex/contrib/draftwatermark.zip
 		http://mirrors.ctan.org/macros/latex/contrib/epigraph.zip
+		http://mirrors.ctan.org/macros/latex/contrib/fvextra.zip
 
 	    2.	Install it by following instructions at:
 		https://help.ubuntu.com/community/LaTeX#Installing_packages_manually
Signature · 1 line
2.17.1
#5 lore raw

PATCH 5/6 howto: Tweak carriagereturn symbol at fvextra's auto line break

In reply to Akira Yokosawa

From beaf1394fd45862ed6ec56bd1d794463113b3049 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Sat, 25 Jan 2020 16:10:24 +0900
Subject: [PATCH 5/6] howto: Tweak carriagereturn symbol at fvextra's auto line break

Also use "darkgray" as the color of symbols indicating the line break to make it obvious that they don't belong to the command line.

Mention the option "-jN" of "make" in comments as well to tell readers that parallel build is possible.

---
 howto/howto.tex | 13 ++++++++-----
 perfbook.tex    |  2 +-
 2 files changed, 9 insertions(+), 6 deletions(-)
howto/howto.tex +8 -5
index de26a113..db538c05 100644
@@ -400,12 +400,15 @@ The required list of packages for a few popular distributions is listed
 in the file \path{FAQ-BUILD.txt} in the \LaTeX{} source to the book.
 
 \begin{listing}[tbp]
-\begin{VerbatimL}[breaklines=true,breakafter=/,numbers=none,xleftmargin=0pt]
+\begin{VerbatimL}[breaklines=true,breakafter=/,
+        breakaftersymbolpre=\raisebox{-.7ex}{\textcolor{darkgray}{\Pisymbol{psy}{191}}},
+	breaksymbolleft=\textcolor{darkgray}{\tiny\ensuremath{\hookrightarrow}},
+        numbers=none,xleftmargin=0pt]
 git clone git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git
 cd perfbook
 # You may need to install a font. See item 1 in FAQ.txt.
-make
-evince perfbook.pdf & # Two-column version
+make                     # -jN for parallel build
+evince perfbook.pdf &    # Two-column version
 make perfbook-1c.pdf
 evince perfbook-1c.pdf & # One-column version for e-readers
 \end{VerbatimL}
@@ -432,8 +435,8 @@ Listing~\ref{lst:howto:Creating a Up-To-Date PDF}.
 \begin{VerbatimL}[numbers=none,xleftmargin=0pt]
 git remote update
 git checkout origin/master
-make
-evince perfbook.pdf & # Two-column version
+make                     # -jN for parallel build
+evince perfbook.pdf &    # Two-column version
 make perfbook-1c.pdf
 evince perfbook-1c.pdf & # One-column version for e-readers
 \end{VerbatimL}
perfbook.tex +1 -1
index 51e1f5e5..87c1eaa1 100644
@@ -50,7 +50,7 @@
 \usepackage{examplep}
 % \usepackage[strings]{underscore}
 % \usepackage{underscore}
-\usepackage{pifont} % special character for qqz reference point
+\usepackage{pifont} % symbols for qqz reference points and carriagereturn
 \usepackage{gensymb} % symbols for both text and math modes such as \degree and \micro
 \usepackage{verbatimbox}[2014/01/30] % for centering verbatim listing in figure environment
 \usepackage{fancyvrb}
Signature · 1 line
2.17.1
#6 lore raw

PATCH 6/6 Remove required version of 'epigraph'

In reply to Akira Yokosawa

From dc553b44983b30584d0f1003a729885b8b7290f2 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Tue, 28 Jan 2020 00:46:52 +0900
Subject: [PATCH 6/6] Remove required version of 'epigraph'

It turned out that the up-to-date "epigraph" doesn't work well with the "nowidow" package on TeX Live 2015/Debian (Ubuntu Xenial) and TeX Live 2016.

Instead, suggest upgrade when the old version is detected and TeX Live version is compatible with the up-to-date "epigraph" package.

This permits TeX Live 2015/Debian (Ubuntu Xenial) to complete the build with the older "epigraph".

Update FAQ-BUILD.txt accordingly.

---
 FAQ-BUILD.txt | 28 +++++++++++++++++++++++-----
 Makefile      | 21 +++++++++++++++++++++
 perfbook.tex  |  2 +-
 3 files changed, 45 insertions(+), 6 deletions(-)
FAQ-BUILD.txt +23 -5
index 98cfb57b..c0bc45aa 100644
@@ -179,14 +179,13 @@
 			tlmgr install newtx
 
 10.	Building perfbook fails with a warning of buggy cleveref/listings,
-	version mismatch of titlesec/draftwatermark/epigraph/fvextra, or
-	missing fvextra. What can I do?
+	version mismatch of titlesec/draftwatermark/fvextra, or missing
+	fvextra. What can I do?
 
 	A.	They are known issues on Ubuntu Xenial (titlesec),
 		Ubuntu Bionic (cleveref), TeX Live 2014/2015 (listings),
 		TeX Live releases prior to 2015 (draftwatermark),
-		TeX Live releases prior to 2017 (fvextra),
-		and TeX Live releases prior to 2020 (epigraph).
+		and TeX Live releases prior to 2017 (fvextra).
 		This answer assumes Ubuntu, but it should work on other
 		distros.
 
@@ -195,7 +194,6 @@
 		http://mirrors.ctan.org/macros/latex/contrib/cleveref.zip
 		http://mirrors.ctan.org/macros/latex/contrib/listings.zip
 		http://mirrors.ctan.org/macros/latex/contrib/draftwatermark.zip
-		http://mirrors.ctan.org/macros/latex/contrib/epigraph.zip
 		http://mirrors.ctan.org/macros/latex/contrib/fvextra.zip
 
 	    2.	Install it by following instructions at:
@@ -257,3 +255,23 @@
 
 		"make neatfreak; make" will rebuild all the figures.
 		The "-jN" option should accelerate the rebuild.
+
+13	Building perfbook has succeeded, but I find some of the
+	epigraphs at bottom of columns/pages.
+	What can I do?
+
+	A.	A new version of "epigraph" package recently released
+		has resolved the issue. You can upgrade it by following
+		the instructions at #10 above.
+		The Up-to-date package can be downloaded from:
+		http://mirrors.ctan.org/macros/latex/contrib/fvextra.zip
+
+	    NOTE: On Tex Live 2015/Debian (Ubuntu Xenial) and TeX Live 2016,
+		the up-to-date "epigraph" does not work properly along
+		with the "nowidow" package.
+		If you'd really like to get rid of orphaned epigraphs,
+		upgrading TeX Live to 2017/Debian (Ubuntu Bionic) or
+		later is the way to go.
+		The updated "epigraph" package is expected to be
+		distributed in upstream TeX Live 2020 and Tex Live 2019/Debian
+		(Ubuntu Focal).
Makefile +21 -0
index 3dbd5d53..d39ab571 100644
@@ -129,6 +129,23 @@ LINEREF_ENV_END     = $(patsubst ./%,%,$(shell grep -R -l -F '\end{lineref}' .))
 LINELABEL_ENV = $(filter-out $(LINE_ENV_IGNORE),$(sort $(LINELABEL_ENV_BEGIN) $(LINELABEL_ENV_END)))
 LINEREF_ENV   = $(filter-out $(LINE_ENV_IGNORE),$(sort $(LINEREF_ENV_BEGIN) $(LINEREF_ENV_END)))
 
+OLD_EPIGRAPH := $(shell grep -c '2009/09/02' `kpsewhich epigraph.sty`)
+TEXLIVE_2015_DEBIAN := $(shell pdftex --version | grep -c 'TeX Live 2015/Debian')
+TEXLIVE_2016 := $(shell pdftex --version | grep -c 'TeX Live 2016')
+ifeq ($(OLD_EPIGRAPH),1)
+  ifeq ($(TEXLIVE_2015_DEBIAN),1)
+    SUGGEST_UPGRADE_EPIGRAPH := 0
+  else
+    ifeq ($(TEXLIVE_2016),1)
+      SUGGEST_UPGRADE_EPIGRAPH := 0
+    else
+      SUGGEST_UPGRADE_EPIGRAPH := 1
+    endif
+  endif
+else
+  SUGGEST_UPGRADE_EPIGRAPH := 0
+endif
+
 SOURCES_OF_SNIPPET_ALL := $(shell grep -R -l -F '\begin{snippet}' CodeSamples)
 SOURCES_OF_LITMUS      := $(shell grep -R -l -F '\begin[snippet]' CodeSamples)
 SOURCES_OF_LTMS        := $(patsubst %.litmus,%.ltms,$(SOURCES_OF_LITMUS))
@@ -167,6 +184,10 @@ mslmmsg:
 
 $(PDFTARGETS): %.pdf: %.tex %.bbl
 	sh utilities/runlatex.sh $(basename $@)
+ifeq ($(SUGGEST_UPGRADE_EPIGRAPH),1)
+	@echo "Consider upgrading 'epigraph' to prevent orphaned epigraphs."
+	@echo "See #13 in FAQ-BUILD.txt."
+endif
 
 $(PDFTARGETS:.pdf=.bbl): %.bbl: %.aux $(BIBSOURCES)
 	bibtex $(basename $@)
perfbook.tex +1 -1
index 87c1eaa1..30796c44 100644
@@ -72,7 +72,7 @@
 \usepackage[bookmarks=true,bookmarksnumbered=true,pdfborder={0 0 0},linktoc=all]{hyperref}
 \usepackage{footnotebackref} % to enable cross-ref of footnote
 \usepackage[all]{hypcap} % for going to the top of figure and table
-\usepackage{epigraph}[2020/01/02] % latest version prevents orphaned epigraph
+\usepackage{epigraph}
 \setlength{\epigraphwidth}{2.6in}
 \usepackage[xspace]{ellipsis}
 \usepackage{braket} % for \ket{} macro in QC section
Signature · 1 line
2.17.1
#7 lore raw
In reply to Akira Yokosawa
Quoted 48 lines · Akira Yokosawa
Quoted 1 line

From dc553b44983b30584d0f1003a729885b8b7290f2 Mon Sep 17 00:00:00 2001

From: Akira Yokosawa <[email protected]>
Date: Thu, 30 Jan 2020 21:13:04 +0900
Subject: [PATCH 0/6] howto: Reduce width of Listings 2.1 and 2.2

Hi Paul,

This patch set has quite a large diff stats despite the small changes in the resulting PDF.
What I am trying here is to enable (semi-) automatic line breaks in code snippets.
The "fvextra" package enhances the capability of fancyvrb. By specifying "breaklines" and "breakafter" options to the VerbatimL environment, snippets with a long line can be typeset as a plain "listing" environment.
I see that Listings 2.1 and 2.2 do not deserve the full width of the page and tried to apply the fvextra approach.

However, there were unfortunate name collisions of custom environments.
"fvextra" requires the "lineno" package, where "linelabel" and "lineref" are used as global variables.

So I need to rename the environments to "fcvlabel" and "fcvref". Patch 1/6 does those renames, hence the large diff stats.

Patch 2/6 adds checks to detect now erroneous uses of "linelabel" and "lineref".
Without this change, as they are defined as LaTeX variables by "lineno", such uses wouldn't be caught by LaTeX as errors, but would end up in undefined references.
The remaining warnings in the log file would be far from pin-point.

Patch 3/6 actually modifies Listings 2.1 and 2.2. At this point, the symbol representing carriagereturn in Listing 2.1 doesn't look good enough to me.
Patch 5/6 takes care of the symbol. It also adds comments to mention the "-jN" option of "make".

Patch 4/6 updates FAQ-BUILD.txt.

Patch 6/6 is an independent change to loosen the required version of "epigraph". It turned out that the combination of the up-to-date "epigraph" and the "nowidow" packages doesn't work properly on TeX Live 2015/Debian (Ubuntu Xenial). On a more recent TeX Live installation where the combination works, a suggestion to upgrade "epigraph" will be output after the build completes.

Quoted 5 lines

As this patch set touches Makefile, please test carefully before pushing out.
Especially, I'd like you to test Patch 2/6 and see if the error message, displayed when you use "linelabel" or "lineref" in place of "fcvlabel" or "fcvref", looks OK to you.

The following error messages looks eminently clear to me:

'linelabel' used as environment in SMPdesign/.SMPdesign.tex.swp SMPdesign/SMPdesign.tex. Use 'fcvlabel' instead.
'lineref' used as environment in SMPdesign/.SMPdesign.tex.swp SMPdesign/SMPdesign.tex. Use 'fcvref' instead.

And the text following:

--
SMPdesign/SMPdesign.tex-1021-\subsubsection{Allocation Function} SMPdesign/SMPdesign.tex-1022- SMPdesign/SMPdesign.tex:1023:\begin{lineref}[ln:SMPdesign:smpalloc:alloc] SMPdesign/SMPdesign.tex-1024-The allocation function \co{memblock_alloc()} may be seen in SMPdesign/SMPdesign.tex-1025-Listing~\ref{lst:SMPdesign:Allocator-Cache Allocator Function}.
------

Is even more helpful! Very good, thank you!

And I love it that the "git clone" command can still be trivially copy-and-pasted from howto/howto.tex.

Queued and pushed, again thank you!!!

Thanx, Paul

Quoted 55 lines

Thanks, Akira
--
Akira Yokosawa (6):
Rename environments 'linelabel' and 'lineref'
Makefile: Check 'linelabel' and 'lineref' used as environment
howto: Reduce width of Listings 2.1 and 2.2
FAQ-BUILD: Add 'fvextra' to the list of packages in item 10
howto: Tweak carriagereturn symbol at fvextra's auto line break Remove required version of 'epigraph'

 FAQ-BUILD.txt                                |  30 ++-
 Makefile                                     |  47 ++++
 SMPdesign/SMPdesign.tex                      |  12 +-
 SMPdesign/beyond.tex                         |  44 ++--
 SMPdesign/partexercises.tex                  |  32 +--
 advsync/advsync.tex                          |   8 +-
 advsync/rt.tex                               |  40 ++--
 appendix/questions/after.tex                 |   4 +-
 appendix/styleguide/samplecodesnippetfcv.tex |   4 +-
 appendix/styleguide/styleguide.tex           |  52 ++--
 appendix/toyrcu/toyrcu.tex                   | 128 +++++-----
 appendix/whymb/whymemorybarriers.tex         |  16 +-
 count/count.tex                              | 200 ++++++++--------
 datastruct/datastruct.tex                    |  80 +++----
 debugging/debugging.tex                      |  12 +-
 defer/defer.tex                              |  16 +-
 defer/hazptr.tex                             |  20 +-
 defer/rcuapi.tex                             |   8 +-
 defer/rcufundamental.tex                     |   4 +-
 defer/rcuintro.tex                           |   4 +-
 defer/rcuusage.tex                           |  52 ++--
 defer/refcnt.tex                             |  20 +-
 defer/seqlock.tex                            |  40 ++--
 formal/axiomatic.tex                         |  40 ++--
 formal/dyntickrcu.tex                        | 148 ++++++------
 formal/ppcmem.tex                            |  24 +-
 formal/spinhint.tex                          |  44 ++--
 future/formalregress.tex                     |   4 +-
 future/htm.tex                               |  28 +--
 howto/howto.tex                              |  57 ++---
 locking/locking-existence.tex                |  20 +-
 locking/locking.tex                          |  76 +++---
 memorder/memorder.tex                        | 240 +++++++++----------
 owned/owned.tex                              |  12 +-
 perfbook.tex                                 |   9 +-
 together/applyrcu.tex                        |  32 +--
 together/refcnt.tex                          |  32 +--
 toolsoftrade/toolsoftrade.tex                | 184 +++++++-------
 utilities/checkfcv.pl                        |   8 +-
 utilities/fcvextract.pl                      |  10 +-
 40 files changed, 956 insertions(+), 885 deletions(-)
Signature · 1 line
2.17.1