Manually convert RCU text files to ReST format
Subsystems (7)
PATCH 1/10 docs: RCU: convert checklist.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Use the right list markups;
- Add it to RCU/index.rst.
---
.../RCU/{checklist.txt => checklist.rst} | 17 ++++++++++++-----
Documentation/RCU/index.rst | 3 +++
2 files changed, 15 insertions(+), 5 deletions(-)
rename Documentation/RCU/{checklist.txt => checklist.rst} (98%)Documentation/RCU/checklist.rst renamed from Documentation/RCU/checklist.txt +12 -5
@@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ Review Checklist for RCU Patches +================================ This document contains a checklist for producing and reviewing patches
@@ -411,18 +415,21 @@ over a rather long period of time, but improvements are always welcome! __rcu sparse checks to validate your RCU code. These can help find problems as follows: - CONFIG_PROVE_LOCKING: check that accesses to RCU-protected data + CONFIG_PROVE_LOCKING: + check that accesses to RCU-protected data structures are carried out under the proper RCU read-side critical section, while holding the right combination of locks, or whatever other conditions are appropriate. - CONFIG_DEBUG_OBJECTS_RCU_HEAD: check that you don't pass the + CONFIG_DEBUG_OBJECTS_RCU_HEAD: + check that you don't pass the same object to call_rcu() (or friends) before an RCU grace period has elapsed since the last time that you passed that same object to call_rcu() (or friends). - __rcu sparse checks: tag the pointer to the RCU-protected data + __rcu sparse checks: + tag the pointer to the RCU-protected data structure with __rcu, and sparse will warn you if you access that pointer without the services of one of the variants of rcu_dereference().
@@ -442,8 +449,8 @@ over a rather long period of time, but improvements are always welcome! You instead need to use one of the barrier functions: - o call_rcu() -> rcu_barrier() - o call_srcu() -> srcu_barrier() + - call_rcu() -> rcu_barrier() + - call_srcu() -> srcu_barrier() However, these barrier functions are absolutely -not- guaranteed to wait for a grace period. In fact, if there are no call_rcu()
Documentation/RCU/index.rst +3 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _rcu_concepts: ============
@@ -8,6 +10,7 @@ RCU concepts :maxdepth: 3 arrayRCU + checklist rcubarrier rcu_dereference whatisRCU
Signature · 1 line
2.25.2
PATCH 3/10 docs: RCU: convert lockdep.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document title;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
Documentation/RCU/{lockdep.txt => lockdep.rst} | 12 ++++++++----
2 files changed, 9 insertions(+), 4 deletions(-)
rename Documentation/RCU/{lockdep.txt => lockdep.rst} (96%)Documentation/RCU/index.rst +1 -0
@@ -11,6 +11,7 @@ RCU concepts arrayRCU checklist + lockdep lockdep-splat rcubarrier rcu_dereference
Documentation/RCU/lockdep.rst renamed from Documentation/RCU/lockdep.txt +8 -4
@@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== RCU and lockdep checking +======================== All flavors of RCU have lockdep checking available, so that lockdep is aware of when each task enters and leaves any flavor of RCU read-side
@@ -8,7 +12,7 @@ tracking to include RCU state, which can sometimes help when debugging deadlocks and the like. In addition, RCU provides the following primitives that check lockdep's -state: +state:: rcu_read_lock_held() for normal RCU. rcu_read_lock_bh_held() for RCU-bh.
@@ -63,7 +67,7 @@ checking of rcu_dereference() primitives: The rcu_dereference_check() check expression can be any boolean expression, but would normally include a lockdep expression. However, any boolean expression can be used. For a moderately ornate example, -consider the following: +consider the following:: file = rcu_dereference_check(fdt->fd[fd], lockdep_is_held(&files->file_lock) ||
@@ -82,7 +86,7 @@ RCU read-side critical sections, in case (2) the ->file_lock prevents any change from taking place, and finally, in case (3) the current task is the only task accessing the file_struct, again preventing any change from taking place. If the above statement was invoked only from updater -code, it could instead be written as follows: +code, it could instead be written as follows:: file = rcu_dereference_protected(fdt->fd[fd], lockdep_is_held(&files->file_lock) ||
@@ -105,7 +109,7 @@ false and they are called from outside any RCU read-side critical section. For example, the workqueue for_each_pwq() macro is intended to be used either within an RCU read-side critical section or with wq->mutex held. -It is thus implemented as follows: +It is thus implemented as follows:: #define for_each_pwq(pwq, wq) list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
Signature · 1 line
2.25.2
cover Manually convert RCU text files to ReST format
This patch series convert RCU patches to ReST.
One interesting point to be noticed hereis that the RTFP.txt file contain a broken TeX bib file. I suspect that someone added some new articles directly there without trying to use LaTeX to check if the addition is valid. Or maybe it is just due to some version differences from the time such references were added.
During the RTFP.txt conversion, I fixed the bibtex problems in order for it to be properly parsed by LaTeX, and used the fixed file to produce a list of the actually used references inside the RTFP.txt file., manually adding them to the converted RTFP.rst.
As not all references were mentioned there, I opted to preserve the converted RTFP.bib, as it could be useful for someone doing any research around RCU.
The results of those changes (together with other changes from my pending doc patches) are available at:
https://www.infradead.org/~mchehab/kernel_docs/RCU/index.html
And the series is on my git tree:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-docs
Mauro Carvalho Chehab (10):
docs: RCU: convert checklist.txt to ReST
docs: RCU: convert lockdep-splat.txt to ReST
docs: RCU: convert lockdep.txt to ReST
docs: RCU: convert rculist_nulls.txt to ReST
docs: RCU: convert torture.txt to ReST
docs: RCU: convert rcuref.txt to ReST
docs: RCU: RTFP: fix bibtex entries
docs: RCU: convert RTFP.txt to ReST
docs: RCU: stallwarn.txt: convert it to ReST
docs: RCU: rculist_nulls.rst: don't duplicate chapter names
Documentation/RCU/{RTFP.txt => RTFP.bib} | 323 ++--------
Documentation/RCU/RTFP.rst | 593 ++++++++++++++++++
.../RCU/{checklist.txt => checklist.rst} | 17 +-
Documentation/RCU/index.rst | 11 +
.../{lockdep-splat.txt => lockdep-splat.rst} | 99 +--
.../RCU/{lockdep.txt => lockdep.rst} | 12 +-
Documentation/RCU/rcu.rst | 4 +-
Documentation/RCU/rculist_nulls.rst | 200 ++++++
Documentation/RCU/rculist_nulls.txt | 172 -----
Documentation/RCU/{rcuref.txt => rcuref.rst} | 193 +++---
.../RCU/{stallwarn.txt => stallwarn.rst} | 55 +-
.../RCU/{torture.txt => torture.rst} | 115 ++--
Documentation/locking/locktorture.rst | 2 +-
MAINTAINERS | 4 +-
include/linux/rculist_nulls.h | 2 +-
kernel/rcu/rcutorture.c | 2 +-
kernel/rcu/tree_stall.h | 4 +-
net/core/sock.c | 4 +-
18 files changed, 1139 insertions(+), 673 deletions(-)
rename Documentation/RCU/{RTFP.txt => RTFP.bib} (82%)
create mode 100644 Documentation/RCU/RTFP.rst
rename Documentation/RCU/{checklist.txt => checklist.rst} (98%)
rename Documentation/RCU/{lockdep-splat.txt => lockdep-splat.rst} (54%)
rename Documentation/RCU/{lockdep.txt => lockdep.rst} (96%)
create mode 100644 Documentation/RCU/rculist_nulls.rst
delete mode 100644 Documentation/RCU/rculist_nulls.txt
rename Documentation/RCU/{rcuref.txt => rcuref.rst} (50%)
rename Documentation/RCU/{stallwarn.txt => stallwarn.rst} (90%)
rename Documentation/RCU/{torture.txt => torture.rst} (76%)Signature · 1 line
2.25.2
PATCH 10/10 docs: RCU: rculist_nulls.rst: don't duplicate chapter names
Since changeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst"), auto-references for chapters are generated. This is a nice feature, but has a drawback: no chapters can have the same sumber.
So, we need to add two higher hierarchy chapters on this document, in order to avoid such duplication.
--- Documentation/RCU/rculist_nulls.rst | 6 ++++++ 1 file changed, 6 insertions(+)
Documentation/RCU/rculist_nulls.rst +6 -0
@@ -10,6 +10,9 @@ objects using SLAB_TYPESAFE_BY_RCU allocations. Please read the basics in Documentation/RCU/listRCU.rst +Using 'nulls' +============= + Using special makers (called 'nulls') is a convenient way to solve following problem :
@@ -126,6 +129,9 @@ very very fast (before the end of RCU grace period) -------------------------------------------------------------------------- +Avoiding extra smp_rmb() +======================== + With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup() and extra smp_wmb() in insert function.
Signature · 1 line
2.25.2
PATCH 8/10 docs: RCU: convert RTFP.txt to ReST
In reply to Mauro Carvalho ChehabThe conversion of this file was not trivial at all.
It had, internally, a bibtex database with 170 references. From those, 72 entries were used at the text.
There were some bugs at the database, as several things there were not really compatible with LaTeX. We had to first solve those issues, with it was done on the previous patch. The end result is now at the RTFP.bib file.
After having RTFP.bib buildable, we converted the RTFP.txt file into a RTFP.tex file using sphinx-build, and we changed the [foo] references to \cite{foo}, fixing some other stuff (on some places, it uses the word "and" with was not recognized).
Then, we added this at the end of the tex file:
\bibliographystyle{abstract}
\bibliography{/devel/v4l/docs/Documentation/RCU/RTFP.bib}With that, we used latex to produce a PDF file.
Then, we manually copied the generated references to the text file, converting it to ReST.
As there are othere references inside the bib database, we're opting to keep the bibliography file at the tree, as it might be useful in the future.
PS.: An alternative approach would be to use the sphinxcontrib-bibtex extension. It didn't work here, as such extension doesn't provide support for "@Conference" notation. We might also use a lot of ".. raw: latex", but, in this case, it won't be able to produce references for html outputs.
---
Documentation/RCU/{RTFP.txt => RTFP.bib} | 225 +--------
Documentation/RCU/RTFP.rst | 593 +++++++++++++++++++++++
Documentation/RCU/index.rst | 2 +
Documentation/RCU/rcu.rst | 4 +-
4 files changed, 603 insertions(+), 221 deletions(-)
rename Documentation/RCU/{RTFP.txt => RTFP.bib} (85%)
create mode 100644 Documentation/RCU/RTFP.rstDocumentation/RCU/RTFP.bib renamed from Documentation/RCU/RTFP.txt +6 -219
@@ -1,222 +1,9 @@ -Read the Fscking Papers! - - -This document describes RCU-related publications, and is followed by -the corresponding bibtex entries. A number of the publications may -be found at http://www.rdrop.com/users/paulmck/RCU/. For others, browsers -and search engines will usually find what you are looking for. - -The first thing resembling RCU was published in 1980, when Kung and Lehman -[Kung80] recommended use of a garbage collector to defer destruction -of nodes in a parallel binary search tree in order to simplify its -implementation. This works well in environments that have garbage -collectors, but most production garbage collectors incur significant -overhead. - -In 1982, Manber and Ladner [Manber82,Manber84] recommended deferring -destruction until all threads running at that time have terminated, again -for a parallel binary search tree. This approach works well in systems -with short-lived threads, such as the K42 research operating system. -However, Linux has long-lived tasks, so more is needed. - -In 1986, Hennessy, Osisek, and Seigh [Hennessy89] introduced passive -serialization, which is an RCU-like mechanism that relies on the presence -of "quiescent states" in the VM/XA hypervisor that are guaranteed not -to be referencing the data structure. However, this mechanism was not -optimized for modern computer systems, which is not surprising given -that these overheads were not so expensive in the mid-80s. Nonetheless, -passive serialization appears to be the first deferred-destruction -mechanism to be used in production. Furthermore, the relevant patent -has lapsed, so this approach may be used in non-GPL software, if desired. -(In contrast, implementation of RCU is permitted only in software licensed -under either GPL or LGPL. Sorry!!!) - -In 1987, Rashid et al. described lazy TLB-flush [RichardRashid87a]. -At first glance, this has nothing to do with RCU, but nevertheless -this paper helped inspire the update-side batching used in the later -RCU implementation in DYNIX/ptx. In 1988, Barbara Liskov published -a description of Argus that noted that use of out-of-date values can -be tolerated in some situations. Thus, this paper provides some early -theoretical justification for use of stale data. - -In 1990, Pugh [Pugh90] noted that explicitly tracking which threads -were reading a given data structure permitted deferred free to operate -in the presence of non-terminating threads. However, this explicit -tracking imposes significant read-side overhead, which is undesirable -in read-mostly situations. This algorithm does take pains to avoid -write-side contention and parallelize the other write-side overheads by -providing a fine-grained locking design, however, it would be interesting -to see how much of the performance advantage reported in 1990 remains -today. - -At about this same time, Andrews [Andrews91textbook] described ``chaotic -relaxation'', where the normal barriers between successive iterations -of convergent numerical algorithms are relaxed, so that iteration $n$ -might use data from iteration $n-1$ or even $n-2$. This introduces -error, which typically slows convergence and thus increases the number of -iterations required. However, this increase is sometimes more than made -up for by a reduction in the number of expensive barrier operations, -which are otherwise required to synchronize the threads at the end -of each iteration. Unfortunately, chaotic relaxation requires highly -structured data, such as the matrices used in scientific programs, and -is thus inapplicable to most data structures in operating-system kernels. - -In 1992, Henry (now Alexia) Massalin completed a dissertation advising -parallel programmers to defer processing when feasible to simplify -synchronization [HMassalinPhD]. RCU makes extremely heavy use of -this advice. - -In 1993, Jacobson [Jacobson93] verbally described what is perhaps the -simplest deferred-free technique: simply waiting a fixed amount of time -before freeing blocks awaiting deferred free. Jacobson did not describe -any write-side changes he might have made in this work using SGI's Irix -kernel. Aju John published a similar technique in 1995 [AjuJohn95]. -This works well if there is a well-defined upper bound on the length of -time that reading threads can hold references, as there might well be in -hard real-time systems. However, if this time is exceeded, perhaps due -to preemption, excessive interrupts, or larger-than-anticipated load, -memory corruption can ensue, with no reasonable means of diagnosis. -Jacobson's technique is therefore inappropriate for use in production -operating-system kernels, except when such kernels can provide hard -real-time response guarantees for all operations. - -Also in 1995, Pu et al. [Pu95a] applied a technique similar to that of Pugh's -read-side-tracking to permit replugging of algorithms within a commercial -Unix operating system. However, this replugging permitted only a single -reader at a time. The following year, this same group of researchers -extended their technique to allow for multiple readers [Cowan96a]. -Their approach requires memory barriers (and thus pipeline stalls), -but reduces memory latency, contention, and locking overheads. - -1995 also saw the first publication of DYNIX/ptx's RCU mechanism -[Slingwine95], which was optimized for modern CPU architectures, -and was successfully applied to a number of situations within the -DYNIX/ptx kernel. The corresponding conference paper appeared in 1998 -[McKenney98]. - -In 1999, the Tornado and K42 groups described their "generations" -mechanism, which is quite similar to RCU [Gamsa99]. These operating -systems made pervasive use of RCU in place of "existence locks", which -greatly simplifies locking hierarchies and helps avoid deadlocks. - -The year 2000 saw an email exchange that would likely have -led to yet another independent invention of something like RCU -[RustyRussell2000a,RustyRussell2000b]. Instead, 2001 saw the first -RCU presentation involving Linux [McKenney01a] at OLS. The resulting -abundance of RCU patches was presented the following year [McKenney02a], -and use of RCU in dcache was first described that same year [Linder02a]. - -Also in 2002, Michael [Michael02b,Michael02a] presented "hazard-pointer" -techniques that defer the destruction of data structures to simplify -non-blocking synchronization (wait-free synchronization, lock-free -synchronization, and obstruction-free synchronization are all examples of -non-blocking synchronization). The corresponding journal article appeared -in 2004 [MagedMichael04a]. This technique eliminates locking, reduces -contention, reduces memory latency for readers, and parallelizes pipeline -stalls and memory latency for writers. However, these techniques still -impose significant read-side overhead in the form of memory barriers. -Researchers at Sun worked along similar lines in the same timeframe -[HerlihyLM02]. These techniques can be thought of as inside-out reference -counts, where the count is represented by the number of hazard pointers -referencing a given data structure rather than the more conventional -counter field within the data structure itself. The key advantage -of inside-out reference counts is that they can be stored in immortal -variables, thus allowing races between access and deletion to be avoided. - -By the same token, RCU can be thought of as a "bulk reference count", -where some form of reference counter covers all reference by a given CPU -or thread during a set timeframe. This timeframe is related to, but -not necessarily exactly the same as, an RCU grace period. In classic -RCU, the reference counter is the per-CPU bit in the "bitmask" field, -and each such bit covers all references that might have been made by -the corresponding CPU during the prior grace period. Of course, RCU -can be thought of in other terms as well. - -In 2003, the K42 group described how RCU could be used to create -hot-pluggable implementations of operating-system functions [Appavoo03a]. -Later that year saw a paper describing an RCU implementation -of System V IPC [Arcangeli03] (following up on a suggestion by -Hugh Dickins [Dickins02a] and an implementation by Mingming Cao -[MingmingCao2002IPCRCU]), and an introduction to RCU in Linux Journal -[McKenney03a]. - -2004 has seen a Linux-Journal article on use of RCU in dcache -[McKenney04a], a performance comparison of locking to RCU on several -different CPUs [McKenney04b], a dissertation describing use of RCU in a -number of operating-system kernels [PaulEdwardMcKenneyPhD], a paper -describing how to make RCU safe for soft-realtime applications [Sarma04c], -and a paper describing SELinux performance with RCU [JamesMorris04b]. - -2005 brought further adaptation of RCU to realtime use, permitting -preemption of RCU realtime critical sections [PaulMcKenney05a, -PaulMcKenney05b]. - -2006 saw the first best-paper award for an RCU paper [ThomasEHart2006a], -as well as further work on efficient implementations of preemptible -RCU [PaulEMcKenney2006b], but priority-boosting of RCU read-side critical -sections proved elusive. An RCU implementation permitting general -blocking in read-side critical sections appeared [PaulEMcKenney2006c], -Robert Olsson described an RCU-protected trie-hash combination -[RobertOlsson2006a]. - -2007 saw the journal version of the award-winning RCU paper from 2006 -[ThomasEHart2007a], as well as a paper demonstrating use of Promela -and Spin to mechanically verify an optimization to Oleg Nesterov's -QRCU [PaulEMcKenney2007QRCUspin], a design document describing -preemptible RCU [PaulEMcKenney2007PreemptibleRCU], and the three-part -LWN "What is RCU?" series [PaulEMcKenney2007WhatIsRCUFundamentally, -PaulEMcKenney2008WhatIsRCUUsage, and PaulEMcKenney2008WhatIsRCUAPI]. - -2008 saw a journal paper on real-time RCU [DinakarGuniguntala2008IBMSysJ], -a history of how Linux changed RCU more than RCU changed Linux -[PaulEMcKenney2008RCUOSR], and a design overview of hierarchical RCU -[PaulEMcKenney2008HierarchicalRCU]. - -2009 introduced user-level RCU algorithms [PaulEMcKenney2009MaliciousURCU], -which Mathieu Desnoyers is now maintaining [MathieuDesnoyers2009URCU] -[MathieuDesnoyersPhD]. TINY_RCU [PaulEMcKenney2009BloatWatchRCU] made -its appearance, as did expedited RCU [PaulEMcKenney2009expeditedRCU]. -The problem of resizable RCU-protected hash tables may now be on a path -to a solution [JoshTriplett2009RPHash]. A few academic researchers are now -using RCU to solve their parallel problems [HariKannan2009DynamicAnalysisRCU]. - -2010 produced a simpler preemptible-RCU implementation -based on TREE_RCU [PaulEMcKenney2010SimpleOptRCU], lockdep-RCU -[PaulEMcKenney2010LockdepRCU], another resizable RCU-protected hash -table [HerbertXu2010RCUResizeHash] (this one consuming more memory, -but allowing arbitrary changes in hash function, as required for DoS -avoidance in the networking code), realization of the 2009 RCU-protected -hash table with atomic node move [JoshTriplett2010RPHash], an update on -the RCU API [PaulEMcKenney2010RCUAPI]. - -2011 marked the inclusion of Nick Piggin's fully lockless dentry search -[LinusTorvalds2011Linux2:6:38:rc1:NPigginVFS], an RCU-protected red-black -tree using software transactional memory to protect concurrent updates -(strange, but true!) [PhilHoward2011RCUTMRBTree], yet another variant of -RCU-protected resizable hash tables [Triplett:2011:RPHash], the 3.0 RCU -trainwreck [PaulEMcKenney2011RCU3.0trainwreck], and Neil Brown's "Meet the -Lockers" LWN article [NeilBrown2011MeetTheLockers]. Some academic -work looked at debugging uses of RCU [Seyster:2011:RFA:2075416.2075425]. - -In 2012, Josh Triplett received his Ph.D. with his dissertation -covering RCU-protected resizable hash tables and the relationship -between memory barriers and read-side traversal order: If the updater -is making changes in the opposite direction from the read-side traveral -order, the updater need only execute a memory-barrier instruction, -but if in the same direction, the updater needs to wait for a grace -period between the individual updates [JoshTriplettPhD]. Also in 2012, -after seventeen years of attempts, an RCU paper made it into a top-flight -academic journal, IEEE Transactions on Parallel and Distributed Systems -[MathieuDesnoyers2012URCU]. A group of researchers in Spain applied -user-level RCU to crowd simulation [GuillermoVigueras2012RCUCrowd], and -another group of researchers in Europe produced a formal description of -RCU based on separation logic [AlexeyGotsman2012VerifyGraceExtended], -which was published in the 2013 European Symposium on Programming -[AlexeyGotsman2013ESOPRCU]. - - - -Bibtex Entries +% +% Note: This file contains the references used when RTFP.rst was created, +% plus ~100 other unused references. While we could probably get rid of +% this file as a hole, I opted to keep it here, as maybe those other +% references could be useful to someone. +% @article{Kung80 ,author="H. T. Kung and Q. Lehman"
Documentation/RCU/RTFP.rst new file +593 -0
593 lines not on this page · raw message
Documentation/RCU/index.rst +2 -0
@@ -24,6 +24,8 @@ RCU concepts NMI-RCU UP + RTFP + Design/Memory-Ordering/Tree-RCU-Memory-Ordering Design/Expedited-Grace-Periods/Expedited-Grace-Periods Design/Requirements/Requirements
Documentation/RCU/rcu.rst +2 -2
@@ -75,7 +75,7 @@ Frequently Asked Questions - I hear that RCU is patented? What is with that? Yes, it is. There are several known patents related to RCU, - search for the string "Patent" in Documentation/RCU/RTFP.txt to find them. + search for the string "Patent" in Documentation/RCU/RTFP.rst to find them. Of these, one was allowed to lapse by the assignee, and the others have been contributed to the Linux kernel under GPL. There are now also LGPL implementations of user-level RCU
@@ -88,5 +88,5 @@ Frequently Asked Questions - Where can I find more information on RCU? - See the Documentation/RCU/RTFP.txt file. + See the Documentation/RCU/RTFP.rst file. Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
Signature · 1 line
2.25.2
PATCH 4/10 docs: RCU: convert rculist_nulls.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
--- Documentation/RCU/index.rst | 1 + Documentation/RCU/rculist_nulls.rst | 194 ++++++++++++++++++++++++++++ Documentation/RCU/rculist_nulls.txt | 172 ------------------------ include/linux/rculist_nulls.h | 2 +- net/core/sock.c | 4 +- 5 files changed, 198 insertions(+), 175 deletions(-) create mode 100644 Documentation/RCU/rculist_nulls.rst delete mode 100644 Documentation/RCU/rculist_nulls.txt
Documentation/RCU/index.rst +1 -0
@@ -17,6 +17,7 @@ RCU concepts rcu_dereference whatisRCU rcu + rculist_nulls listRCU NMI-RCU UP
Documentation/RCU/rculist_nulls.rst new file +194 -0
194 lines not on this page · raw message
Documentation/RCU/rculist_nulls.txt deleted +0 -172
172 lines not on this page · raw message
include/linux/rculist_nulls.h +1 -1
@@ -162,7 +162,7 @@ static inline void hlist_nulls_add_fake(struct hlist_nulls_node *n)* The barrier() is needed to make sure compiler doesn't cache first element [1], * as this loop can be restarted [2] * [1] Documentation/core-api/atomic_ops.rst around line 114 -* [2] Documentation/RCU/rculist_nulls.txt around line 146 +* [2] Documentation/RCU/rculist_nulls.rst around line 146 */ #define hlist_nulls_for_each_entry_rcu (tpos, pos, head, member) \ for (({barrier();}), \
net/core/sock.c +2 -2
@@ -1883,7 +1883,7 @@ struct sock *sk_clone_lock(const struct sock *sk, const gfp_t priority)/* * Before updating sk_refcnt, we must commit prior changes to memory -* (Documentation/RCU/rculist_nulls.txt for details) +* (Documentation/RCU/rculist_nulls.rst for details) */ smp_wmb ();refcount_set (&newsk->sk_refcnt,2 );
@@ -2945,7 +2945,7 @@ void sock_init_data(struct socket *sock, struct sock *sk)sk_rx_queue_clear (sk);/* * Before updating sk_refcnt, we must commit prior changes to memory -* (Documentation/RCU/rculist_nulls.txt for details) +* (Documentation/RCU/rculist_nulls.rst for details) */ smp_wmb ();refcount_set (&sk->sk_refcnt,1 );
Signature · 1 line
2.25.2
PATCH 5/10 docs: RCU: convert torture.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
.../RCU/{torture.txt => torture.rst} | 115 ++++++++++--------
Documentation/locking/locktorture.rst | 2 +-
MAINTAINERS | 4 +-
kernel/rcu/rcutorture.c | 2 +-
5 files changed, 68 insertions(+), 56 deletions(-)
rename Documentation/RCU/{torture.txt => torture.rst} (76%)Documentation/RCU/index.rst +1 -0
@@ -18,6 +18,7 @@ RCU concepts whatisRCU rcu rculist_nulls + torture listRCU NMI-RCU UP
Documentation/RCU/torture.rst renamed from Documentation/RCU/torture.txt +63 -52
250 lines not on this page · raw message
Documentation/locking/locktorture.rst +1 -1
@@ -166,4 +166,4 @@ checked for such errors. The "rmmod" command forces a "SUCCESS", two are self-explanatory, while the last indicates that while there were no locking failures, CPU-hotplug problems were detected. -Also see: Documentation/RCU/torture.txt +Also see: Documentation/RCU/torture.rst
MAINTAINERS +2 -2
@@ -14309,7 +14309,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev F: Documentation/RCU/ F: include/linux/rcu* F: kernel/rcu/ -X: Documentation/RCU/torture.txt +X: Documentation/RCU/torture.rst X: include/linux/srcu*.h X: kernel/rcu/srcu*.c
@@ -17101,7 +17101,7 @@ M: Josh Triplett <[email protected]> L: [email protected] S: Supported T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev -F: Documentation/RCU/torture.txt +F: Documentation/RCU/torture.rst F: kernel/locking/locktorture.c F: kernel/rcu/rcuperf.c F: kernel/rcu/rcutorture.c
kernel/rcu/rcutorture.c +1 -1
@@ -7,7 +7,7 @@* Authors: Paul E. McKenney <[email protected]> * Josh Triplett <[email protected]> * -* See also: Documentation/RCU/torture.txt +* See also: Documentation/RCU/torture.rst */ #define pr_fmt (fmt) fmt
Signature · 1 line
2.25.2
PATCH 7/10 docs: RCU: RTFP: fix bibtex entries
In reply to Mauro Carvalho ChehabThere are several troubles at the bibtex entries with prevent them to be processed by LaTeX:
- On LaTeX, comment lines start with '%', but here, comments are starting with "#";
- Underlines should be escaped.
- While the best would be to use \url{} for all URL entries, let's do it at least for a couple that would otherwise produce errors on LaTeX.
--- Documentation/RCU/RTFP.txt | 98 +++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 49 deletions(-)
Documentation/RCU/RTFP.txt +49 -49
@@ -231,7 +231,7 @@ Bibtex Entries Use garbage collector to clean up data after everyone is done with it. . Oldest use of something vaguely resembling RCU that I have found. - http://portal.acm.org/citation.cfm?id=320619&dl=GUIDE, + \url{http://portal.acm.org/citation.cfm?id=320619&dl=GUIDE}, [Viewed December 3, 2007] } }
@@ -379,7 +379,7 @@ for Programming Languages and Operating Systems}" } } -# Was Adams91, see also syncrefs.bib. +% Was Adams91, see also syncrefs.bib. @Book{Andrews91textbook ,Author="Gregory R. Andrews" ,title="Concurrent Programming, Principles, and Practices"
@@ -566,7 +566,7 @@ Operating System Design and Implementation}" Use of RCU-like facility in K42/Tornado. Another independent invention of RCU. See especially pages 7-9 (Section 5). - http://www.usenix.org/events/osdi99/full_papers/gamsa/gamsa.pdf + \url{http://www.usenix.org/events/osdi99/full_papers/gamsa/gamsa.pdf} [Viewed August 30, 2006] } }
@@ -1037,10 +1037,10 @@ Add per-cpu batch counter" RCU runs reasonably on a 512-CPU SGI using Manfred Spraul's patches, which may be found at: https://lkml.org/lkml/2004/5/20/49 (split vars into cachelines) - https://lkml.org/lkml/2004/5/22/114 (cpu_quiet() patch) + https://lkml.org/lkml/2004/5/22/114 (cpu\_quiet() patch) https://lkml.org/lkml/2004/5/25/24 (0/5) https://lkml.org/lkml/2004/5/25/23 (1/5) - https://lkml.org/lkml/2004/5/25/265 (works for Jack) + https://lkml.org/lkml/2004/5/25/265 (works for Jack) https://lkml.org/lkml/2004/5/25/20 (2/5) https://lkml.org/lkml/2004/5/25/22 (3/5) https://lkml.org/lkml/2004/5/25/19 (4/5)
@@ -1109,7 +1109,7 @@ Oregon Health and Sciences University" \url{http://lkml.org/lkml/2004/8/6/237} [Viewed June 8, 2010]" ,annotation={ - Introduce rcu_dereference(). + Introduce rcu\_dereference(). } }
@@ -1122,7 +1122,7 @@ Oregon Health and Sciences University" \url{http://lkml.org/lkml/2004/8/30/87} [Viewed February 17, 2005]" ,annotation={ - Uses active code in rcu_read_lock() and rcu_read_unlock() to + Uses active code in rcu\_read\_lock() and rcu\_read\_unlock() to make RCU happen, allowing RCU to function on CPUs that do not receive a scheduling-clock interrupt. }
@@ -1134,7 +1134,7 @@ Oregon Health and Sciences University" ,month="October" ,year="2004" ,note="Available: -\url{http://www.cs.toronto.edu/~tomhart/masters_thesis.html} +\url{http://www.cs.toronto.edu/~tomhart/masters\_thesis.html} [Viewed October 15, 2004]" ,annotation={ Proposes comparing RCU to lock-free methods for the Linux kernel.
@@ -1150,7 +1150,7 @@ Oregon Health and Sciences University" \url{http://marc.theaimsgroup.com/?t=109395731700004&r=1&w=2} [Viewed October 18, 2004]" ,annotation={ - Srivatsa's RCU patch for tcp_ehash lookup. + Srivatsa's RCU patch for tcp\_ehash lookup. } }
@@ -1182,14 +1182,14 @@ Oregon Health and Sciences University" @unpublished{PaulEMcKenney2004rcu:assign:pointer ,Author="Paul E. McKenney" -,Title="{[PATCH 1/3] RCU: \url{rcu_assign_pointer()} removal of memory barriers}" +,Title="{[PATCH 1/3] RCU: \url{rcu\_assign\_pointer()} removal of memory barriers}" ,month="October" ,year="2004" ,note="Available: \url{http://lkml.org/lkml/2004/10/23/241} [Viewed June 8, 2010]" ,annotation={ - Introduce rcu_assign_pointer(). + Introduce rcu\_assign\_pointer(). } }
@@ -1283,7 +1283,7 @@ Data Structures" @unpublished{JonCorbet2005DeprecateSyncKernel ,Author="Jonathan Corbet" -,Title="API change: synchronize_kernel() deprecated" +,Title="API change: synchronize\_kernel() deprecated" ,month="May" ,day="3" ,year="2005"
@@ -1291,8 +1291,8 @@ Data Structures" \url{http://lwn.net/Articles/134484/} [Viewed May 3, 2005]" ,annotation={ - Jon Corbet describes deprecation of synchronize_kernel() - in favor of synchronize_rcu() and synchronize_sched(). + Jon Corbet describes deprecation of synchronize\_kernel() + in favor of synchronize\_rcu() and synchronize\_sched(). } }
@@ -1306,7 +1306,7 @@ Data Structures" [Viewed May 13, 2005]" ,annotation={ First publication of working lock-based deferred free patches - for the CONFIG_PREEMPT_RT environment. + for the CONFIG\_PREEMPT\_RT environment. } }
@@ -1511,7 +1511,7 @@ Canis Rufus and Zoicon5 and Anome and Hal Eisen" ,Year="2006" ,pages="v2 249-254" ,note="Available: -\url{http://www.linuxsymposium.org/2006/view_abstract.php?content_key=184} +\url{http://www.linuxsymposium.org/2006/view\_abstract.php?content\_key=184} [Viewed January 11, 2009]" ,annotation={ Uses RCU-protected radix tree for a lockless page cache.
@@ -1606,8 +1606,8 @@ Revised: @unpublished{JensAxboe2006SlowSRCU ,Author="Jens Axboe" -,Title="Re: [patch] cpufreq: mark \url{cpufreq_tsc()} as -\url{core_initcall_sync}" +,Title="Re: [patch] cpufreq: mark \url{cpufreq\_tsc()} as +\url{core\_initcall\_sync}" ,month="November" ,year="2006" ,day=17
@@ -1701,7 +1701,7 @@ Revised: } } -# CoreyMinyard2007list_splice_rcu +% CoreyMinyard2007list_splice_rcu @unpublished{CoreyMinyard2007list:splice:rcu ,Author="Corey Minyard and Paul E. McKenney" ,Title="{[PATCH]} add an {RCU} version of list splicing"
@@ -1712,7 +1712,7 @@ Revised: \url{http://lkml.org/lkml/2007/1/3/112} [Viewed May 28, 2007]" ,annotation={ - Patch for list_splice_rcu(). + Patch for list\_splice\_rcu(). } }
@@ -1726,7 +1726,7 @@ Revised: \url{http://lwn.net/Articles/217484/} [Viewed November 22, 2007]" ,annotation={ - LWN article introducing the rcu_barrier() primitive. + LWN article introducing the rcu\_barrier() primitive. } }
@@ -1925,7 +1925,7 @@ Revised: } } -# MathieuDesnoyers2007call_rcu_schedNeeded +% MathieuDesnoyers2007call_rcu_schedNeeded @unpublished{MathieuDesnoyers2007call:rcu:schedNeeded ,Author="Mathieu Desnoyers" ,Title="Re: [patch 1/2] {Linux} Kernel Markers - Support Multiple Probes"
@@ -1936,18 +1936,18 @@ Revised: \url{http://lkml.org/lkml/2007/12/20/244} [Viewed March 27, 2008]" ,annotation={ - Request for call_rcu_sched() and rcu_barrier_sched(). + Request for call\_rcu\_sched() and rcu\_barrier\_sched(). } } -######################################################################## -# -# "What is RCU?" LWN series. -# -# http://lwn.net/Articles/262464/ (What is RCU, Fundamentally?) -# http://lwn.net/Articles/263130/ (What is RCU's Usage?) -# http://lwn.net/Articles/264090/ (What is RCU's API?) +%####################################################################### +% +% "What is RCU?" LWN series. +% +% http://lwn.net/Articles/262464/ (What is RCU, Fundamentally?) +% http://lwn.net/Articles/263130/ (What is RCU's Usage?) +% http://lwn.net/Articles/264090/ (What is RCU's API?) @unpublished{PaulEMcKenney2007WhatIsRCUFundamentally ,Author="Paul E. McKenney and Jonathan Walpole"
@@ -2000,10 +2000,10 @@ Revised: } } -# -# "What is RCU?" LWN series. -# -######################################################################## +% +% "What is RCU?" LWN series. +% +%####################################################################### @unpublished{SteveRostedt2008dyntickRCUpatch
@@ -2093,7 +2093,7 @@ lot of {Linux} into your technology!!!" ,annotation={ Updated RCU classic algorithm. Introduced multi-tailed list for RCU callbacks and also pulling common code into - __call_rcu(). + \_\_call\_rcu(). } }
@@ -2145,7 +2145,7 @@ lot of {Linux} into your technology!!!" } } -# Was PaulEMcKenney2011cyclicRCU +% Was PaulEMcKenney2011cyclicRCU @techreport{PaulEMcKenney2008cyclicRCU ,author="Paul E. McKenney" ,title="Efficient Support of Consistent Cyclic Search With Read-Copy Update"
@@ -2353,7 +2353,7 @@ lot of {Linux} into your technology!!!" \url{http://lkml.org/lkml/2009/10/18/129} [Viewed December 29, 2009]" ,annotation={ - Mathieu proposed defer_rcu() with fixed-size per-thread pool + Mathieu proposed defer\_rcu() with fixed-size per-thread pool of RCU callbacks. } }
@@ -2413,8 +2413,8 @@ lot of {Linux} into your technology!!!" \url{http://www.rdrop.com/users/paulmck/RCU/SimplicityThruOptimization.2010.01.21f.pdf} [Viewed October 10, 2010]" ,annotation={ - TREE_PREEMPT_RCU optimizations greatly simplified the old - PREEMPT_RCU implementation. + TREE\_PREEMPT\_RCU optimizations greatly simplified the old + PREEMPT\_RCU implementation. } }
@@ -2426,7 +2426,7 @@ lot of {Linux} into your technology!!!" ,day="1" ,note="\url{https://lwn.net/Articles/371986/}" ,annotation={ - CONFIG_PROVE_RCU, or at least an early version. + CONFIG\_PROVE\_RCU, or at least an early version. [Viewed June 4, 2010] } }
@@ -2454,7 +2454,7 @@ lot of {Linux} into your technology!!!" \url{http://thread.gmane.org/gmane.linux.network/153338} [Viewed June 9, 2014]" ,annotation={ - Use a pair of list_head structures to support RCU-protected + Use a pair of list\_head structures to support RCU-protected resizable hash tables. } }
@@ -2466,7 +2466,7 @@ lot of {Linux} into your technology!!!" ,year="2010" ,annotation={ Data-race detector incorporating RCU. - http://www.filesystems.org/docs/abhinav-thesis/abhinav_thesis.pdf + \url{http://www.filesystems.org/docs/abhinav-thesis/abhinav_thesis.pdf} } }
@@ -2528,7 +2528,7 @@ lot of {Linux} into your technology!!!" nice about it is that it actually improves performance a lot even for single-threaded loads (on an SMP kernel), because it gets rid of some of the most expensive parts of path component lookup, which was the - d_lock on every component lookup. So I'm seeing improvements of 30-50% + d\_lock on every component lookup. So I'm seeing improvements of 30-50% on some seriously pathname-lookup intensive loads." } }
@@ -2551,7 +2551,7 @@ lot of {Linux} into your technology!!!" ,location = {Berkeley, CA} ,pages = {1--6} ,numpages = {6} -,url = {http://www.usenix.org/event/hotpar11/tech/final_files/Howard.pdf} +,url = {http://www.usenix.org/event/hotpar11/tech/final\_files/Howard.pdf} ,publisher = {USENIX Association} ,address = {Berkeley, CA, USA} }
@@ -2581,7 +2581,7 @@ lot of {Linux} into your technology!!!" ,year = {2011} ,pages = {145--158} ,numpages = {14} -,url={http://www.usenix.org/event/atc11/tech/final_files/Triplett.pdf} +,url={http://www.usenix.org/event/atc11/tech/final\_files/Triplett.pdf} ,publisher = {The USENIX Association} ,address = {Portland, OR USA} }
@@ -2690,7 +2690,7 @@ lot of {Linux} into your technology!!!" \url{http://www.rdrop.com/users/paulmck/RCU/RCUdynticks.2012.02.15b.pdf} [Viewed March 1, 2012]" ,annotation={ - RCU_FAST_NO_HZ, round 2. + RCU\_FAST\_NO\_HZ, round 2. } }
@@ -2719,7 +2719,7 @@ lot of {Linux} into your technology!!!" ,note="\url{http://lwn.net/Articles/508991/}" ,annotation={ A couple of simple specific compiler optimizations that motivate - ACCESS_ONCE(). + ACCESS\_ONCE(). } }
@@ -2741,7 +2741,7 @@ lot of {Linux} into your technology!!!" ,month="September" ,day="17" ,year="2012" -,url=http://rdrop.com/users/paulmck/techreports/survey.2012.09.17a.pdf +,url={http://rdrop.com/users/paulmck/techreports/survey.2012.09.17a.pdf} ,note="Technical report paulmck.2012.09.17" ,annotation={ Overview of the first variant of no-CBs CPUs for RCU.
@@ -2807,6 +2807,6 @@ lot of {Linux} into your technology!!!" ,year="2013" ,note="\url{http://lwn.net/Articles/541037/}" ,annotation={ - Getting rid of TINY_PREEMPT_RCU. + Getting rid of TINY\_PREEMPT\_RCU. } }
Signature · 1 line
2.25.2
PATCH 9/10 docs: RCU: stallwarn.txt: convert it to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document and section titles;
- Fix list markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
.../RCU/{stallwarn.txt => stallwarn.rst} | 55 ++++++++++++-------
kernel/rcu/tree_stall.h | 4 +-
3 files changed, 37 insertions(+), 23 deletions(-)
rename Documentation/RCU/{stallwarn.txt => stallwarn.rst} (90%)Documentation/RCU/index.rst +1 -0
@@ -20,6 +20,7 @@ RCU concepts rculist_nulls rcuref torture + stallwarn listRCU NMI-RCU UP
Documentation/RCU/stallwarn.rst renamed from Documentation/RCU/stallwarn.txt +34 -21
193 lines not on this page · raw message
kernel/rcu/tree_stall.h +2 -2
@@ -468,7 +468,7 @@ static void print_other_cpu_stall(unsigned long gp_seq, unsigned long gps)/* * OK, time to rat on our buddy... -* See Documentation/RCU/stallwarn.txt for info on how to debug +* See Documentation/RCU/stallwarn.rst for info on how to debug * RCU CPU stall warnings. */ pr_err ("INFO: %s detected stalls on CPUs/tasks:\n" , rcu_state.name);
@@ -535,7 +535,7 @@ static void print_cpu_stall(unsigned long gps)/* * OK, time to rat on ourselves... -* See Documentation/RCU/stallwarn.txt for info on how to debug +* See Documentation/RCU/stallwarn.rst for info on how to debug * RCU CPU stall warnings. */ pr_err ("INFO: %s self-detected stall on CPU\n" , rcu_state.name);
Signature · 1 line
2.25.2
PATCH 6/10 docs: RCU: convert rcuref.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
Documentation/RCU/{rcuref.txt => rcuref.rst} | 193 ++++++++++---------
2 files changed, 101 insertions(+), 93 deletions(-)
rename Documentation/RCU/{rcuref.txt => rcuref.rst} (50%)Documentation/RCU/index.rst +1 -0
@@ -18,6 +18,7 @@ RCU concepts whatisRCU rcu rculist_nulls + rcuref torture listRCU NMI-RCU
Documentation/RCU/rcuref.rst renamed from Documentation/RCU/rcuref.txt +100 -93
230 lines not on this page · raw message
Signature · 1 line
2.25.2
PATCH 2/10 docs: RCU: convert lockdep-splat.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
.../{lockdep-splat.txt => lockdep-splat.rst} | 99 ++++++++++---------
2 files changed, 53 insertions(+), 47 deletions(-)
rename Documentation/RCU/{lockdep-splat.txt => lockdep-splat.rst} (54%)Documentation/RCU/index.rst +1 -0
@@ -11,6 +11,7 @@ RCU concepts arrayRCU checklist + lockdep-splat rcubarrier rcu_dereference whatisRCU
Documentation/RCU/lockdep-splat.rst renamed from Documentation/RCU/lockdep-splat.txt +52 -47
131 lines not on this page · raw message
Signature · 1 line
2.25.2
Paul E. McKenney
maintainerRe: [PATCH 07/10] docs: RCU: RTFP: fix bibtex entries
In reply to Mauro Carvalho ChehabQuoted 11 lines · Mauro Carvalho Chehab
There are several troubles at the bibtex entries with prevent them to be processed by LaTeX:
- On LaTeX, comment lines start with '%', but here, comments are starting with "#";
- Underlines should be escaped.
- While the best would be to use \url{} for all URL entries, let's do it at least for a couple that would otherwise produce errors on LaTeX.Signed-off-by Mauro Carvalho Chehab <[email protected]>
Another approach might be just to link to a public repo containing cleaned-up versions of these bibliography entries:
https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git/tree/bib/RCU.bib
That would have the advantage of keeping this information in only one place, and reducing the number of updates required.
Thoughts?
Thanx, Paul
Quoted 358 lines
--- Documentation/RCU/RTFP.txt | 98 +++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 49 deletions(-)Documentation/RCU/RTFP.txt +49
-49@@ -231,7 +231,7 @@ Bibtex Entries Use garbage collector to clean up data after everyone is done with it. . Oldest use of something vaguely resembling RCU that I have found. - http://portal.acm.org/citation.cfm?id=320619&dl=GUIDE, + \url{http://portal.acm.org/citation.cfm?id=320619&dl=GUIDE}, [Viewed December 3, 2007] } }@@ -379,7 +379,7 @@ for Programming Languages and Operating Systems}" } } -# Was Adams91, see also syncrefs.bib. +% Was Adams91, see also syncrefs.bib. @Book{Andrews91textbook ,Author="Gregory R. Andrews" ,title="Concurrent Programming, Principles, and Practices"@@ -566,7 +566,7 @@ Operating System Design and Implementation}" Use of RCU-like facility in K42/Tornado. Another independent invention of RCU. See especially pages 7-9 (Section 5). - http://www.usenix.org/events/osdi99/full_papers/gamsa/gamsa.pdf + \url{http://www.usenix.org/events/osdi99/full_papers/gamsa/gamsa.pdf} [Viewed August 30, 2006] } }@@ -1037,10 +1037,10 @@ Add per-cpu batch counter" RCU runs reasonably on a 512-CPU SGI using Manfred Spraul's patches, which may be found at: https://lkml.org/lkml/2004/5/20/49 (split vars into cachelines) - https://lkml.org/lkml/2004/5/22/114 (cpu_quiet() patch) + https://lkml.org/lkml/2004/5/22/114 (cpu\_quiet() patch) https://lkml.org/lkml/2004/5/25/24 (0/5) https://lkml.org/lkml/2004/5/25/23 (1/5) - https://lkml.org/lkml/2004/5/25/265 (works for Jack) + https://lkml.org/lkml/2004/5/25/265 (works for Jack) https://lkml.org/lkml/2004/5/25/20 (2/5) https://lkml.org/lkml/2004/5/25/22 (3/5) https://lkml.org/lkml/2004/5/25/19 (4/5)@@ -1109,7 +1109,7 @@ Oregon Health and Sciences University" \url{http://lkml.org/lkml/2004/8/6/237} [Viewed June 8, 2010]" ,annotation={ - Introduce rcu_dereference(). + Introduce rcu\_dereference(). } }@@ -1122,7 +1122,7 @@ Oregon Health and Sciences University" \url{http://lkml.org/lkml/2004/8/30/87} [Viewed February 17, 2005]" ,annotation={ - Uses active code in rcu_read_lock() and rcu_read_unlock() to + Uses active code in rcu\_read\_lock() and rcu\_read\_unlock() to make RCU happen, allowing RCU to function on CPUs that do not receive a scheduling-clock interrupt. }@@ -1134,7 +1134,7 @@ Oregon Health and Sciences University" ,month="October" ,year="2004" ,note="Available: -\url{http://www.cs.toronto.edu/~tomhart/masters_thesis.html} +\url{http://www.cs.toronto.edu/~tomhart/masters\_thesis.html} [Viewed October 15, 2004]" ,annotation={ Proposes comparing RCU to lock-free methods for the Linux kernel.@@ -1150,7 +1150,7 @@ Oregon Health and Sciences University" \url{http://marc.theaimsgroup.com/?t=109395731700004&r=1&w=2} [Viewed October 18, 2004]" ,annotation={ - Srivatsa's RCU patch for tcp_ehash lookup. + Srivatsa's RCU patch for tcp\_ehash lookup. } }@@ -1182,14 +1182,14 @@ Oregon Health and Sciences University" @unpublished{PaulEMcKenney2004rcu:assign:pointer ,Author="Paul E. McKenney" -,Title="{[PATCH 1/3] RCU: \url{rcu_assign_pointer()} removal of memory barriers}" +,Title="{[PATCH 1/3] RCU: \url{rcu\_assign\_pointer()} removal of memory barriers}" ,month="October" ,year="2004" ,note="Available: \url{http://lkml.org/lkml/2004/10/23/241} [Viewed June 8, 2010]" ,annotation={ - Introduce rcu_assign_pointer(). + Introduce rcu\_assign\_pointer(). } }@@ -1283,7 +1283,7 @@ Data Structures" @unpublished{JonCorbet2005DeprecateSyncKernel ,Author="Jonathan Corbet" -,Title="API change: synchronize_kernel() deprecated" +,Title="API change: synchronize\_kernel() deprecated" ,month="May" ,day="3" ,year="2005"@@ -1291,8 +1291,8 @@ Data Structures" \url{http://lwn.net/Articles/134484/} [Viewed May 3, 2005]" ,annotation={ - Jon Corbet describes deprecation of synchronize_kernel() - in favor of synchronize_rcu() and synchronize_sched(). + Jon Corbet describes deprecation of synchronize\_kernel() + in favor of synchronize\_rcu() and synchronize\_sched(). } }@@ -1306,7 +1306,7 @@ Data Structures" [Viewed May 13, 2005]" ,annotation={ First publication of working lock-based deferred free patches - for the CONFIG_PREEMPT_RT environment. + for the CONFIG\_PREEMPT\_RT environment. } }@@ -1511,7 +1511,7 @@ Canis Rufus and Zoicon5 and Anome and Hal Eisen" ,Year="2006" ,pages="v2 249-254" ,note="Available: -\url{http://www.linuxsymposium.org/2006/view_abstract.php?content_key=184} +\url{http://www.linuxsymposium.org/2006/view\_abstract.php?content\_key=184} [Viewed January 11, 2009]" ,annotation={ Uses RCU-protected radix tree for a lockless page cache.@@ -1606,8 +1606,8 @@ Revised: @unpublished{JensAxboe2006SlowSRCU ,Author="Jens Axboe" -,Title="Re: [patch] cpufreq: mark \url{cpufreq_tsc()} as -\url{core_initcall_sync}" +,Title="Re: [patch] cpufreq: mark \url{cpufreq\_tsc()} as +\url{core\_initcall\_sync}" ,month="November" ,year="2006" ,day=17@@ -1701,7 +1701,7 @@ Revised: } } -# CoreyMinyard2007list_splice_rcu +% CoreyMinyard2007list_splice_rcu @unpublished{CoreyMinyard2007list:splice:rcu ,Author="Corey Minyard and Paul E. McKenney" ,Title="{[PATCH]} add an {RCU} version of list splicing"@@ -1712,7 +1712,7 @@ Revised: \url{http://lkml.org/lkml/2007/1/3/112} [Viewed May 28, 2007]" ,annotation={ - Patch for list_splice_rcu(). + Patch for list\_splice\_rcu(). } }@@ -1726,7 +1726,7 @@ Revised: \url{http://lwn.net/Articles/217484/} [Viewed November 22, 2007]" ,annotation={ - LWN article introducing the rcu_barrier() primitive. + LWN article introducing the rcu\_barrier() primitive. } }@@ -1925,7 +1925,7 @@ Revised: } } -# MathieuDesnoyers2007call_rcu_schedNeeded +% MathieuDesnoyers2007call_rcu_schedNeeded @unpublished{MathieuDesnoyers2007call:rcu:schedNeeded ,Author="Mathieu Desnoyers" ,Title="Re: [patch 1/2] {Linux} Kernel Markers - Support Multiple Probes"@@ -1936,18 +1936,18 @@ Revised: \url{http://lkml.org/lkml/2007/12/20/244} [Viewed March 27, 2008]" ,annotation={ - Request for call_rcu_sched() and rcu_barrier_sched(). + Request for call\_rcu\_sched() and rcu\_barrier\_sched(). } } -######################################################################## -# -# "What is RCU?" LWN series. -# -# http://lwn.net/Articles/262464/ (What is RCU, Fundamentally?) -# http://lwn.net/Articles/263130/ (What is RCU's Usage?) -# http://lwn.net/Articles/264090/ (What is RCU's API?) +%####################################################################### +% +% "What is RCU?" LWN series. +% +% http://lwn.net/Articles/262464/ (What is RCU, Fundamentally?) +% http://lwn.net/Articles/263130/ (What is RCU's Usage?) +% http://lwn.net/Articles/264090/ (What is RCU's API?) @unpublished{PaulEMcKenney2007WhatIsRCUFundamentally ,Author="Paul E. McKenney and Jonathan Walpole"@@ -2000,10 +2000,10 @@ Revised: } } -# -# "What is RCU?" LWN series. -# -######################################################################## +% +% "What is RCU?" LWN series. +% +%####################################################################### @unpublished{SteveRostedt2008dyntickRCUpatch@@ -2093,7 +2093,7 @@ lot of {Linux} into your technology!!!" ,annotation={ Updated RCU classic algorithm. Introduced multi-tailed list for RCU callbacks and also pulling common code into - __call_rcu(). + \_\_call\_rcu(). } }@@ -2145,7 +2145,7 @@ lot of {Linux} into your technology!!!" } } -# Was PaulEMcKenney2011cyclicRCU +% Was PaulEMcKenney2011cyclicRCU @techreport{PaulEMcKenney2008cyclicRCU ,author="Paul E. McKenney" ,title="Efficient Support of Consistent Cyclic Search With Read-Copy Update"@@ -2353,7 +2353,7 @@ lot of {Linux} into your technology!!!" \url{http://lkml.org/lkml/2009/10/18/129} [Viewed December 29, 2009]" ,annotation={ - Mathieu proposed defer_rcu() with fixed-size per-thread pool + Mathieu proposed defer\_rcu() with fixed-size per-thread pool of RCU callbacks. } }@@ -2413,8 +2413,8 @@ lot of {Linux} into your technology!!!" \url{http://www.rdrop.com/users/paulmck/RCU/SimplicityThruOptimization.2010.01.21f.pdf} [Viewed October 10, 2010]" ,annotation={ - TREE_PREEMPT_RCU optimizations greatly simplified the old - PREEMPT_RCU implementation. + TREE\_PREEMPT\_RCU optimizations greatly simplified the old + PREEMPT\_RCU implementation. } }@@ -2426,7 +2426,7 @@ lot of {Linux} into your technology!!!" ,day="1" ,note="\url{https://lwn.net/Articles/371986/}" ,annotation={ - CONFIG_PROVE_RCU, or at least an early version. + CONFIG\_PROVE\_RCU, or at least an early version. [Viewed June 4, 2010] } }@@ -2454,7 +2454,7 @@ lot of {Linux} into your technology!!!" \url{http://thread.gmane.org/gmane.linux.network/153338} [Viewed June 9, 2014]" ,annotation={ - Use a pair of list_head structures to support RCU-protected + Use a pair of list\_head structures to support RCU-protected resizable hash tables. } }@@ -2466,7 +2466,7 @@ lot of {Linux} into your technology!!!" ,year="2010" ,annotation={ Data-race detector incorporating RCU. - http://www.filesystems.org/docs/abhinav-thesis/abhinav_thesis.pdf + \url{http://www.filesystems.org/docs/abhinav-thesis/abhinav_thesis.pdf} } }@@ -2528,7 +2528,7 @@ lot of {Linux} into your technology!!!" nice about it is that it actually improves performance a lot even for single-threaded loads (on an SMP kernel), because it gets rid of some of the most expensive parts of path component lookup, which was the - d_lock on every component lookup. So I'm seeing improvements of 30-50% + d\_lock on every component lookup. So I'm seeing improvements of 30-50% on some seriously pathname-lookup intensive loads." } }@@ -2551,7 +2551,7 @@ lot of {Linux} into your technology!!!" ,location = {Berkeley, CA} ,pages = {1--6} ,numpages = {6} -,url = {http://www.usenix.org/event/hotpar11/tech/final_files/Howard.pdf} +,url = {http://www.usenix.org/event/hotpar11/tech/final\_files/Howard.pdf} ,publisher = {USENIX Association} ,address = {Berkeley, CA, USA} }@@ -2581,7 +2581,7 @@ lot of {Linux} into your technology!!!" ,year = {2011} ,pages = {145--158} ,numpages = {14} -,url={http://www.usenix.org/event/atc11/tech/final_files/Triplett.pdf} +,url={http://www.usenix.org/event/atc11/tech/final\_files/Triplett.pdf} ,publisher = {The USENIX Association} ,address = {Portland, OR USA} }@@ -2690,7 +2690,7 @@ lot of {Linux} into your technology!!!" \url{http://www.rdrop.com/users/paulmck/RCU/RCUdynticks.2012.02.15b.pdf} [Viewed March 1, 2012]" ,annotation={ - RCU_FAST_NO_HZ, round 2. + RCU\_FAST\_NO\_HZ, round 2. } }@@ -2719,7 +2719,7 @@ lot of {Linux} into your technology!!!" ,note="\url{http://lwn.net/Articles/508991/}" ,annotation={ A couple of simple specific compiler optimizations that motivate - ACCESS_ONCE(). + ACCESS\_ONCE(). } }@@ -2741,7 +2741,7 @@ lot of {Linux} into your technology!!!" ,month="September" ,day="17" ,year="2012" -,url=http://rdrop.com/users/paulmck/techreports/survey.2012.09.17a.pdf +,url={http://rdrop.com/users/paulmck/techreports/survey.2012.09.17a.pdf} ,note="Technical report paulmck.2012.09.17" ,annotation={ Overview of the first variant of no-CBs CPUs for RCU.@@ -2807,6 +2807,6 @@ lot of {Linux} into your technology!!!" ,year="2013" ,note="\url{http://lwn.net/Articles/541037/}" ,annotation={ - Getting rid of TINY_PREEMPT_RCU. + Getting rid of TINY\_PREEMPT\_RCU. } }Signature · 1 line
2.25.2
Paul E. McKenney
maintainerRe: [PATCH 07/10] docs: RCU: RTFP: fix bibtex entries
Quoted 16 lines · Paul E. McKenney
Quoted 11 lines · Mauro Carvalho Chehab
There are several troubles at the bibtex entries with prevent them to be processed by LaTeX:
- On LaTeX, comment lines start with '%', but here, comments are starting with "#";
- Underlines should be escaped.
- While the best would be to use \url{} for all URL entries, let's do it at least for a couple that would otherwise produce errors on LaTeX.Signed-off-by Mauro Carvalho Chehab <[email protected]>Another approach might be just to link to a public repo containing cleaned-up versions of these bibliography entries:
Quoted 6 lines
https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git/tree/bib/RCU.bib
That would have the advantage of keeping this information in only one place, and reducing the number of updates required.
Thoughts?
OK, I should have read the next patch in the series, where you convert into a Sphinx-compatible bibliography. Except that you had to convert the bibtex entries by hand to produce the Sphinx-compatible entries? That will get a bit ugly when it comes time to add more entries.
Or was the conversion of bibliography entries automated?
Thanx, Paul
Quoted 358 lines
Quoted 358 lines
--- Documentation/RCU/RTFP.txt | 98 +++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 49 deletions(-)Documentation/RCU/RTFP.txt +49
-49@@ -231,7 +231,7 @@ Bibtex Entries Use garbage collector to clean up data after everyone is done with it. . Oldest use of something vaguely resembling RCU that I have found. - http://portal.acm.org/citation.cfm?id=320619&dl=GUIDE, + \url{http://portal.acm.org/citation.cfm?id=320619&dl=GUIDE}, [Viewed December 3, 2007] } }@@ -379,7 +379,7 @@ for Programming Languages and Operating Systems}" } } -# Was Adams91, see also syncrefs.bib. +% Was Adams91, see also syncrefs.bib. @Book{Andrews91textbook ,Author="Gregory R. Andrews" ,title="Concurrent Programming, Principles, and Practices"@@ -566,7 +566,7 @@ Operating System Design and Implementation}" Use of RCU-like facility in K42/Tornado. Another independent invention of RCU. See especially pages 7-9 (Section 5). - http://www.usenix.org/events/osdi99/full_papers/gamsa/gamsa.pdf + \url{http://www.usenix.org/events/osdi99/full_papers/gamsa/gamsa.pdf} [Viewed August 30, 2006] } }@@ -1037,10 +1037,10 @@ Add per-cpu batch counter" RCU runs reasonably on a 512-CPU SGI using Manfred Spraul's patches, which may be found at: https://lkml.org/lkml/2004/5/20/49 (split vars into cachelines) - https://lkml.org/lkml/2004/5/22/114 (cpu_quiet() patch) + https://lkml.org/lkml/2004/5/22/114 (cpu\_quiet() patch) https://lkml.org/lkml/2004/5/25/24 (0/5) https://lkml.org/lkml/2004/5/25/23 (1/5) - https://lkml.org/lkml/2004/5/25/265 (works for Jack) + https://lkml.org/lkml/2004/5/25/265 (works for Jack) https://lkml.org/lkml/2004/5/25/20 (2/5) https://lkml.org/lkml/2004/5/25/22 (3/5) https://lkml.org/lkml/2004/5/25/19 (4/5)@@ -1109,7 +1109,7 @@ Oregon Health and Sciences University" \url{http://lkml.org/lkml/2004/8/6/237} [Viewed June 8, 2010]" ,annotation={ - Introduce rcu_dereference(). + Introduce rcu\_dereference(). } }@@ -1122,7 +1122,7 @@ Oregon Health and Sciences University" \url{http://lkml.org/lkml/2004/8/30/87} [Viewed February 17, 2005]" ,annotation={ - Uses active code in rcu_read_lock() and rcu_read_unlock() to + Uses active code in rcu\_read\_lock() and rcu\_read\_unlock() to make RCU happen, allowing RCU to function on CPUs that do not receive a scheduling-clock interrupt. }@@ -1134,7 +1134,7 @@ Oregon Health and Sciences University" ,month="October" ,year="2004" ,note="Available: -\url{http://www.cs.toronto.edu/~tomhart/masters_thesis.html} +\url{http://www.cs.toronto.edu/~tomhart/masters\_thesis.html} [Viewed October 15, 2004]" ,annotation={ Proposes comparing RCU to lock-free methods for the Linux kernel.@@ -1150,7 +1150,7 @@ Oregon Health and Sciences University" \url{http://marc.theaimsgroup.com/?t=109395731700004&r=1&w=2} [Viewed October 18, 2004]" ,annotation={ - Srivatsa's RCU patch for tcp_ehash lookup. + Srivatsa's RCU patch for tcp\_ehash lookup. } }@@ -1182,14 +1182,14 @@ Oregon Health and Sciences University" @unpublished{PaulEMcKenney2004rcu:assign:pointer ,Author="Paul E. McKenney" -,Title="{[PATCH 1/3] RCU: \url{rcu_assign_pointer()} removal of memory barriers}" +,Title="{[PATCH 1/3] RCU: \url{rcu\_assign\_pointer()} removal of memory barriers}" ,month="October" ,year="2004" ,note="Available: \url{http://lkml.org/lkml/2004/10/23/241} [Viewed June 8, 2010]" ,annotation={ - Introduce rcu_assign_pointer(). + Introduce rcu\_assign\_pointer(). } }@@ -1283,7 +1283,7 @@ Data Structures" @unpublished{JonCorbet2005DeprecateSyncKernel ,Author="Jonathan Corbet" -,Title="API change: synchronize_kernel() deprecated" +,Title="API change: synchronize\_kernel() deprecated" ,month="May" ,day="3" ,year="2005"@@ -1291,8 +1291,8 @@ Data Structures" \url{http://lwn.net/Articles/134484/} [Viewed May 3, 2005]" ,annotation={ - Jon Corbet describes deprecation of synchronize_kernel() - in favor of synchronize_rcu() and synchronize_sched(). + Jon Corbet describes deprecation of synchronize\_kernel() + in favor of synchronize\_rcu() and synchronize\_sched(). } }@@ -1306,7 +1306,7 @@ Data Structures" [Viewed May 13, 2005]" ,annotation={ First publication of working lock-based deferred free patches - for the CONFIG_PREEMPT_RT environment. + for the CONFIG\_PREEMPT\_RT environment. } }@@ -1511,7 +1511,7 @@ Canis Rufus and Zoicon5 and Anome and Hal Eisen" ,Year="2006" ,pages="v2 249-254" ,note="Available: -\url{http://www.linuxsymposium.org/2006/view_abstract.php?content_key=184} +\url{http://www.linuxsymposium.org/2006/view\_abstract.php?content\_key=184} [Viewed January 11, 2009]" ,annotation={ Uses RCU-protected radix tree for a lockless page cache.@@ -1606,8 +1606,8 @@ Revised: @unpublished{JensAxboe2006SlowSRCU ,Author="Jens Axboe" -,Title="Re: [patch] cpufreq: mark \url{cpufreq_tsc()} as -\url{core_initcall_sync}" +,Title="Re: [patch] cpufreq: mark \url{cpufreq\_tsc()} as +\url{core\_initcall\_sync}" ,month="November" ,year="2006" ,day=17@@ -1701,7 +1701,7 @@ Revised: } } -# CoreyMinyard2007list_splice_rcu +% CoreyMinyard2007list_splice_rcu @unpublished{CoreyMinyard2007list:splice:rcu ,Author="Corey Minyard and Paul E. McKenney" ,Title="{[PATCH]} add an {RCU} version of list splicing"@@ -1712,7 +1712,7 @@ Revised: \url{http://lkml.org/lkml/2007/1/3/112} [Viewed May 28, 2007]" ,annotation={ - Patch for list_splice_rcu(). + Patch for list\_splice\_rcu(). } }@@ -1726,7 +1726,7 @@ Revised: \url{http://lwn.net/Articles/217484/} [Viewed November 22, 2007]" ,annotation={ - LWN article introducing the rcu_barrier() primitive. + LWN article introducing the rcu\_barrier() primitive. } }@@ -1925,7 +1925,7 @@ Revised: } } -# MathieuDesnoyers2007call_rcu_schedNeeded +% MathieuDesnoyers2007call_rcu_schedNeeded @unpublished{MathieuDesnoyers2007call:rcu:schedNeeded ,Author="Mathieu Desnoyers" ,Title="Re: [patch 1/2] {Linux} Kernel Markers - Support Multiple Probes"@@ -1936,18 +1936,18 @@ Revised: \url{http://lkml.org/lkml/2007/12/20/244} [Viewed March 27, 2008]" ,annotation={ - Request for call_rcu_sched() and rcu_barrier_sched(). + Request for call\_rcu\_sched() and rcu\_barrier\_sched(). } } -######################################################################## -# -# "What is RCU?" LWN series. -# -# http://lwn.net/Articles/262464/ (What is RCU, Fundamentally?) -# http://lwn.net/Articles/263130/ (What is RCU's Usage?) -# http://lwn.net/Articles/264090/ (What is RCU's API?) +%####################################################################### +% +% "What is RCU?" LWN series. +% +% http://lwn.net/Articles/262464/ (What is RCU, Fundamentally?) +% http://lwn.net/Articles/263130/ (What is RCU's Usage?) +% http://lwn.net/Articles/264090/ (What is RCU's API?) @unpublished{PaulEMcKenney2007WhatIsRCUFundamentally ,Author="Paul E. McKenney and Jonathan Walpole"@@ -2000,10 +2000,10 @@ Revised: } } -# -# "What is RCU?" LWN series. -# -######################################################################## +% +% "What is RCU?" LWN series. +% +%####################################################################### @unpublished{SteveRostedt2008dyntickRCUpatch@@ -2093,7 +2093,7 @@ lot of {Linux} into your technology!!!" ,annotation={ Updated RCU classic algorithm. Introduced multi-tailed list for RCU callbacks and also pulling common code into - __call_rcu(). + \_\_call\_rcu(). } }@@ -2145,7 +2145,7 @@ lot of {Linux} into your technology!!!" } } -# Was PaulEMcKenney2011cyclicRCU +% Was PaulEMcKenney2011cyclicRCU @techreport{PaulEMcKenney2008cyclicRCU ,author="Paul E. McKenney" ,title="Efficient Support of Consistent Cyclic Search With Read-Copy Update"@@ -2353,7 +2353,7 @@ lot of {Linux} into your technology!!!" \url{http://lkml.org/lkml/2009/10/18/129} [Viewed December 29, 2009]" ,annotation={ - Mathieu proposed defer_rcu() with fixed-size per-thread pool + Mathieu proposed defer\_rcu() with fixed-size per-thread pool of RCU callbacks. } }@@ -2413,8 +2413,8 @@ lot of {Linux} into your technology!!!" \url{http://www.rdrop.com/users/paulmck/RCU/SimplicityThruOptimization.2010.01.21f.pdf} [Viewed October 10, 2010]" ,annotation={ - TREE_PREEMPT_RCU optimizations greatly simplified the old - PREEMPT_RCU implementation. + TREE\_PREEMPT\_RCU optimizations greatly simplified the old + PREEMPT\_RCU implementation. } }@@ -2426,7 +2426,7 @@ lot of {Linux} into your technology!!!" ,day="1" ,note="\url{https://lwn.net/Articles/371986/}" ,annotation={ - CONFIG_PROVE_RCU, or at least an early version. + CONFIG\_PROVE\_RCU, or at least an early version. [Viewed June 4, 2010] } }@@ -2454,7 +2454,7 @@ lot of {Linux} into your technology!!!" \url{http://thread.gmane.org/gmane.linux.network/153338} [Viewed June 9, 2014]" ,annotation={ - Use a pair of list_head structures to support RCU-protected + Use a pair of list\_head structures to support RCU-protected resizable hash tables. } }@@ -2466,7 +2466,7 @@ lot of {Linux} into your technology!!!" ,year="2010" ,annotation={ Data-race detector incorporating RCU. - http://www.filesystems.org/docs/abhinav-thesis/abhinav_thesis.pdf + \url{http://www.filesystems.org/docs/abhinav-thesis/abhinav_thesis.pdf} } }@@ -2528,7 +2528,7 @@ lot of {Linux} into your technology!!!" nice about it is that it actually improves performance a lot even for single-threaded loads (on an SMP kernel), because it gets rid of some of the most expensive parts of path component lookup, which was the - d_lock on every component lookup. So I'm seeing improvements of 30-50% + d\_lock on every component lookup. So I'm seeing improvements of 30-50% on some seriously pathname-lookup intensive loads." } }@@ -2551,7 +2551,7 @@ lot of {Linux} into your technology!!!" ,location = {Berkeley, CA} ,pages = {1--6} ,numpages = {6} -,url = {http://www.usenix.org/event/hotpar11/tech/final_files/Howard.pdf} +,url = {http://www.usenix.org/event/hotpar11/tech/final\_files/Howard.pdf} ,publisher = {USENIX Association} ,address = {Berkeley, CA, USA} }@@ -2581,7 +2581,7 @@ lot of {Linux} into your technology!!!" ,year = {2011} ,pages = {145--158} ,numpages = {14} -,url={http://www.usenix.org/event/atc11/tech/final_files/Triplett.pdf} +,url={http://www.usenix.org/event/atc11/tech/final\_files/Triplett.pdf} ,publisher = {The USENIX Association} ,address = {Portland, OR USA} }@@ -2690,7 +2690,7 @@ lot of {Linux} into your technology!!!" \url{http://www.rdrop.com/users/paulmck/RCU/RCUdynticks.2012.02.15b.pdf} [Viewed March 1, 2012]" ,annotation={ - RCU_FAST_NO_HZ, round 2. + RCU\_FAST\_NO\_HZ, round 2. } }@@ -2719,7 +2719,7 @@ lot of {Linux} into your technology!!!" ,note="\url{http://lwn.net/Articles/508991/}" ,annotation={ A couple of simple specific compiler optimizations that motivate - ACCESS_ONCE(). + ACCESS\_ONCE(). } }@@ -2741,7 +2741,7 @@ lot of {Linux} into your technology!!!" ,month="September" ,day="17" ,year="2012" -,url=http://rdrop.com/users/paulmck/techreports/survey.2012.09.17a.pdf +,url={http://rdrop.com/users/paulmck/techreports/survey.2012.09.17a.pdf} ,note="Technical report paulmck.2012.09.17" ,annotation={ Overview of the first variant of no-CBs CPUs for RCU.@@ -2807,6 +2807,6 @@ lot of {Linux} into your technology!!!" ,year="2013" ,note="\url{http://lwn.net/Articles/541037/}" ,annotation={ - Getting rid of TINY_PREEMPT_RCU. + Getting rid of TINY\_PREEMPT\_RCU. } }Signature · 1 line
2.25.2
Paul E. McKenney
maintainerQuoted 17 lines · Mauro Carvalho Chehab
This patch series convert RCU patches to ReST.
One interesting point to be noticed hereis that the RTFP.txt file contain a broken TeX bib file. I suspect that someone added some new articles directly there without trying to use LaTeX to check if the addition is valid. Or maybe it is just due to some version differences from the time such references were added.
During the RTFP.txt conversion, I fixed the bibtex problems in order for it to be properly parsed by LaTeX, and used the fixed file to produce a list of the actually used references inside the RTFP.txt file., manually adding them to the converted
RTFP.rst.As not all references were mentioned there, I opted to preserve the converted RTFP.bib, as it could be useful for someone doing any research around RCU.
Quoted 8 lines
The results of those changes (together with other changes from my pending doc patches) are available at:
https://www.infradead.org/~mchehab/kernel_docs/RCU/index.html
And the series is on my git tree:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-docs
I queued all but 7/10 and 8/10, for which I have the bibtex-to-ReST conversion question. Thank you for dragging these files kicking and screaming into the year 2020! ;-)
Thanx, Paul
Quoted 46 lines
Mauro Carvalho Chehab (10):
docs: RCU: convert checklist.txt to ReST
docs: RCU: convert lockdep-splat.txt to ReST
docs: RCU: convert lockdep.txt to ReST
docs: RCU: convert rculist_nulls.txt to ReST
docs: RCU: convert torture.txt to ReST
docs: RCU: convert rcuref.txt to ReST
docs: RCU: RTFP: fix bibtex entries
docs: RCU: convert RTFP.txt to ReST
docs: RCU: stallwarn.txt: convert it to ReST
docs: RCU:rculist_nulls.rst: don't duplicate chapter namesDocumentation/RCU/{RTFP.txt => RTFP.bib} | 323 ++-------- Documentation/RCU/RTFP.rst | 593 ++++++++++++++++++ .../RCU/{checklist.txt => checklist.rst} | 17 +- Documentation/RCU/index.rst | 11 + .../{lockdep-splat.txt => lockdep-splat.rst} | 99 +-- .../RCU/{lockdep.txt => lockdep.rst} | 12 +- Documentation/RCU/rcu.rst | 4 +- Documentation/RCU/rculist_nulls.rst | 200 ++++++ Documentation/RCU/rculist_nulls.txt | 172 ----- Documentation/RCU/{rcuref.txt => rcuref.rst} | 193 +++--- .../RCU/{stallwarn.txt => stallwarn.rst} | 55 +- .../RCU/{torture.txt => torture.rst} | 115 ++-- Documentation/locking/locktorture.rst | 2 +- MAINTAINERS | 4 +- include/linux/rculist_nulls.h | 2 +- kernel/rcu/rcutorture.c | 2 +- kernel/rcu/tree_stall.h | 4 +- net/core/sock.c | 4 +- 18 files changed, 1139 insertions(+), 673 deletions(-) rename Documentation/RCU/{RTFP.txt => RTFP.bib} (82%) create mode 100644 Documentation/RCU/RTFP.rst rename Documentation/RCU/{checklist.txt => checklist.rst} (98%) rename Documentation/RCU/{lockdep-splat.txt => lockdep-splat.rst} (54%) rename Documentation/RCU/{lockdep.txt => lockdep.rst} (96%) create mode 100644 Documentation/RCU/rculist_nulls.rst delete mode 100644 Documentation/RCU/rculist_nulls.txt rename Documentation/RCU/{rcuref.txt => rcuref.rst} (50%) rename Documentation/RCU/{stallwarn.txt => stallwarn.rst} (90%) rename Documentation/RCU/{torture.txt => torture.rst} (76%)Signature · 1 line
2.25.2
Re: [PATCH 07/10] docs: RCU: RTFP: fix bibtex entries
In reply to Paul E. McKenneyEm Tue, 21 Apr 2020 10:52:25 -0700
"Paul E. McKenney" <[email protected]> escreveu:
Quoted 14 lines · Paul E. McKenney
Quoted 13 lines · Mauro Carvalho Chehab
Quoted 11 lines
There are several troubles at the bibtex entries with prevent them to be processed by LaTeX:
- On LaTeX, comment lines start with '%', but here, comments are starting with "#";
- Underlines should be escaped.
- While the best would be to use \url{} for all URL entries, let's do it at least for a couple that would otherwise produce errors on LaTeX.Signed-off-by Mauro Carvalho Chehab <[email protected]>
Quoted 7 lines
Quoted 7 lines
Another approach might be just to link to a public repo containing cleaned-up versions of these bibliography entries:
https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git/tree/bib/RCU.bib
That would have the advantage of keeping this information in only one place, and reducing the number of updates required.
Yeah. I didn't know you had it somewhere else.
Quoted 6 lines
Quoted 2 lines
Thoughts?
OK, I should have read the next patch in the series, where you convert into a Sphinx-compatible bibliography. Except that you had to convert the bibtex entries by hand to produce the Sphinx-compatible entries?
No, but it still required a lot of manual work.
I manually converted the file to ReST. That was the easiest part.
Then, I used sphinx-build to convert it into a LaTeX file and changed the produced .tex for it to use the .bib file.
The last step was the hardest one. I'm not familiar with LaTeX. I did several attempts to produce an output with the same kind of captions as the original file, but I was unable to generate it.
So, I ended doing the final step the hard way: I used XeLaTeX to produce a PDF file. Then, I manually copied the entries from the output back into the ReST file, carefully adjusting the captions, in order for them to point to the right places.
Before that, I tried to use a few Sphinx BibTeX extensions, but they are not complete: they were unable to parse some types of entries. If I'm not mistaken (I did it some time ago, on another computer), the ones I tested crashed when trying to parse some entries, like '@Conference'.
Quoted 3 lines
That will get a bit ugly when it comes time to add more entries.
Or was the conversion of bibliography entries automated?
I suspect it should be possible to automate it, but, as I said, I'm not too familiar with LaTeX.
Thanks,
Mauro
Paul E. McKenney
maintainerRe: [PATCH 07/10] docs: RCU: RTFP: fix bibtex entries
Quoted 50 lines · Mauro Carvalho Chehab
Em Tue, 21 Apr 2020 10:52:25 -0700
"Paul E. McKenney" <[email protected]> escreveu:Quoted 14 lines · Paul E. McKenney
Quoted 13 lines · Mauro Carvalho Chehab
Quoted 11 lines
There are several troubles at the bibtex entries with prevent them to be processed by LaTeX:
- On LaTeX, comment lines start with '%', but here, comments are starting with "#";
- Underlines should be escaped.
- While the best would be to use \url{} for all URL entries, let's do it at least for a couple that would otherwise produce errors on LaTeX.Signed-off-by Mauro Carvalho Chehab <[email protected]>Quoted 7 lines
Quoted 7 lines
Another approach might be just to link to a public repo containing cleaned-up versions of these bibliography entries:
https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/perfbook.git/tree/bib/RCU.bib
That would have the advantage of keeping this information in only one place, and reducing the number of updates required.
Yeah. I didn't know you had it somewhere else.
Quoted 6 lines
Quoted 2 lines
Thoughts?
OK, I should have read the next patch in the series, where you convert into a Sphinx-compatible bibliography. Except that you had to convert the bibtex entries by hand to produce the Sphinx-compatible entries?
No, but it still required a lot of manual work.
I manually converted the file to ReST. That was the easiest part.
Then, I used sphinx-build to convert it into a LaTeX file and changed the produced .tex for it to use the .bib file.
The last step was the hardest one. I'm not familiar with LaTeX. I did several attempts to produce an output with the same kind of captions as the original file, but I was unable to generate it.
So, I ended doing the final step the hard way: I used XeLaTeX to produce a PDF file. Then, I manually copied the entries from the output back into the ReST file, carefully adjusting the captions, in order for them to point to the right places.
Quoted 5 lines
Before that, I tried to use a few Sphinx BibTeX extensions, but they are not complete: they were unable to parse some types of entries. If I'm not mistaken (I did it some time ago, on another computer), the ones I tested crashed when trying to parse some entries, like '@Conference'.
OK, that sounds decidedly non-trivial. :-(
Quoted 6 lines
Quoted 3 lines
That will get a bit ugly when it comes time to add more entries.
Or was the conversion of bibliography entries automated?
I suspect it should be possible to automate it, but, as I said, I'm not too familiar with LaTeX.
In the meantime, would it work to just reference the RCU.bib URL above?
Thanx, Paul