howto: Reduce width of Listings 2.1 and 2.2
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
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
@@ -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
@@ -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
@@ -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
@@ -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, ×tart) != 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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/spinhint.tex +22 -22
44 lines not on this page · 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
toolsoftrade/toolsoftrade.tex +92 -92
184 lines not on this page · 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.
PATCH 2/6 Makefile: Check 'linelabel' and 'lineref' used as environment
In reply to Akira YokosawaFrom 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
@@ -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
PATCH 3/6 howto: Reduce width of Listings 2.1 and 2.2
In reply to Akira YokosawaFrom 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
@@ -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
@@ -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
PATCH 4/6 FAQ-BUILD: Add 'fvextra' to the list of packages in item 10
In reply to Akira YokosawaFrom 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
@@ -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
PATCH 5/6 howto: Tweak carriagereturn symbol at fvextra's auto line break
In reply to Akira YokosawaFrom 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
@@ -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
@@ -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
PATCH 6/6 Remove required version of 'epigraph'
In reply to Akira YokosawaFrom 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
@@ -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
@@ -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
@@ -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
Paul E. McKenney
AppliedQuoted 48 lines · Akira Yokosawa
Quoted 1 line
From
dc553b44983b30584d0f1003a729885b8b7290f2Mon Sep 17 00:00:00 2001From: 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.2Hi 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