[PATCH 00/10] Manually convert RCU text files to ReST format

[PATCH 00/10] Manually convert RCU text files to ReST format

[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.

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%)

-- 
2.25.2

[PATCH 01/10] docs: RCU: convert checklist.txt to ReST

[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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../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%)

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.rst
similarity index 98%
rename from Documentation/RCU/checklist.txt
rename to Documentation/RCU/checklist.rst
index e98ff261a438..2efed9926c3f 100644
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.rst
@@ -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()
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 81a0a1e5f767..c1ba4d130bb0 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -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
-- 
2.25.2

[PATCH 02/10] docs: RCU: convert lockdep-splat.txt to ReST

[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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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%)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index c1ba4d130bb0..430a37132b2c 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -11,6 +11,7 @@ RCU concepts
 
    arrayRCU
    checklist
+   lockdep-splat
    rcubarrier
    rcu_dereference
    whatisRCU
diff --git a/Documentation/RCU/lockdep-splat.txt b/Documentation/RCU/lockdep-splat.rst
similarity index 54%
rename from Documentation/RCU/lockdep-splat.txt
rename to Documentation/RCU/lockdep-splat.rst
index b8096316fd11..2a5c79db57dc 100644
--- a/Documentation/RCU/lockdep-splat.txt
+++ b/Documentation/RCU/lockdep-splat.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+Lockdep-RCU Splat
+=================
+
 Lockdep-RCU was added to the Linux kernel in early 2010
 (http://lwn.net/Articles/371986/).  This facility checks for some common
 misuses of the RCU API, most notably using one of the rcu_dereference()
@@ -12,55 +18,54 @@ overwriting or worse.  There can of course be false positives, this
 being the real world and all that.
 
 So let's look at an example RCU lockdep splat from 3.0-rc5, one that
-has long since been fixed:
+has long since been fixed::
 
-=============================
-WARNING: suspicious RCU usage
------------------------------
-block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage!
+    =============================
+    WARNING: suspicious RCU usage
+    -----------------------------
+    block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage!
 
-other info that might help us debug this:
+other info that might help us debug this::
 
+    rcu_scheduler_active = 1, debug_locks = 0
+    3 locks held by scsi_scan_6/1552:
+    #0:  (&shost->scan_mutex){+.+.}, at: [<ffffffff8145efca>]
+    scsi_scan_host_selected+0x5a/0x150
+    #1:  (&eq->sysfs_lock){+.+.}, at: [<ffffffff812a5032>]
+    elevator_exit+0x22/0x60
+    #2:  (&(&q->__queue_lock)->rlock){-.-.}, at: [<ffffffff812b6233>]
+    cfq_exit_queue+0x43/0x190
 
-rcu_scheduler_active = 1, debug_locks = 0
-3 locks held by scsi_scan_6/1552:
- #0:  (&shost->scan_mutex){+.+.}, at: [<ffffffff8145efca>]
-scsi_scan_host_selected+0x5a/0x150
- #1:  (&eq->sysfs_lock){+.+.}, at: [<ffffffff812a5032>]
-elevator_exit+0x22/0x60
- #2:  (&(&q->__queue_lock)->rlock){-.-.}, at: [<ffffffff812b6233>]
-cfq_exit_queue+0x43/0x190
+    stack backtrace:
+    Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17
+    Call Trace:
+    [<ffffffff810abb9b>] lockdep_rcu_dereference+0xbb/0xc0
+    [<ffffffff812b6139>] __cfq_exit_single_io_context+0xe9/0x120
+    [<ffffffff812b626c>] cfq_exit_queue+0x7c/0x190
+    [<ffffffff812a5046>] elevator_exit+0x36/0x60
+    [<ffffffff812a802a>] blk_cleanup_queue+0x4a/0x60
+    [<ffffffff8145cc09>] scsi_free_queue+0x9/0x10
+    [<ffffffff81460944>] __scsi_remove_device+0x84/0xd0
+    [<ffffffff8145dca3>] scsi_probe_and_add_lun+0x353/0xb10
+    [<ffffffff817da069>] ? error_exit+0x29/0xb0
+    [<ffffffff817d98ed>] ? _raw_spin_unlock_irqrestore+0x3d/0x80
+    [<ffffffff8145e722>] __scsi_scan_target+0x112/0x680
+    [<ffffffff812c690d>] ? trace_hardirqs_off_thunk+0x3a/0x3c
+    [<ffffffff817da069>] ? error_exit+0x29/0xb0
+    [<ffffffff812bcc60>] ? kobject_del+0x40/0x40
+    [<ffffffff8145ed16>] scsi_scan_channel+0x86/0xb0
+    [<ffffffff8145f0b0>] scsi_scan_host_selected+0x140/0x150
+    [<ffffffff8145f149>] do_scsi_scan_host+0x89/0x90
+    [<ffffffff8145f170>] do_scan_async+0x20/0x160
+    [<ffffffff8145f150>] ? do_scsi_scan_host+0x90/0x90
+    [<ffffffff810975b6>] kthread+0xa6/0xb0
+    [<ffffffff817db154>] kernel_thread_helper+0x4/0x10
+    [<ffffffff81066430>] ? finish_task_switch+0x80/0x110
+    [<ffffffff817d9c04>] ? retint_restore_args+0xe/0xe
+    [<ffffffff81097510>] ? __kthread_init_worker+0x70/0x70
+    [<ffffffff817db150>] ? gs_change+0xb/0xb
 
-stack backtrace:
-Pid: 1552, comm: scsi_scan_6 Not tainted 3.0.0-rc5 #17
-Call Trace:
- [<ffffffff810abb9b>] lockdep_rcu_dereference+0xbb/0xc0
- [<ffffffff812b6139>] __cfq_exit_single_io_context+0xe9/0x120
- [<ffffffff812b626c>] cfq_exit_queue+0x7c/0x190
- [<ffffffff812a5046>] elevator_exit+0x36/0x60
- [<ffffffff812a802a>] blk_cleanup_queue+0x4a/0x60
- [<ffffffff8145cc09>] scsi_free_queue+0x9/0x10
- [<ffffffff81460944>] __scsi_remove_device+0x84/0xd0
- [<ffffffff8145dca3>] scsi_probe_and_add_lun+0x353/0xb10
- [<ffffffff817da069>] ? error_exit+0x29/0xb0
- [<ffffffff817d98ed>] ? _raw_spin_unlock_irqrestore+0x3d/0x80
- [<ffffffff8145e722>] __scsi_scan_target+0x112/0x680
- [<ffffffff812c690d>] ? trace_hardirqs_off_thunk+0x3a/0x3c
- [<ffffffff817da069>] ? error_exit+0x29/0xb0
- [<ffffffff812bcc60>] ? kobject_del+0x40/0x40
- [<ffffffff8145ed16>] scsi_scan_channel+0x86/0xb0
- [<ffffffff8145f0b0>] scsi_scan_host_selected+0x140/0x150
- [<ffffffff8145f149>] do_scsi_scan_host+0x89/0x90
- [<ffffffff8145f170>] do_scan_async+0x20/0x160
- [<ffffffff8145f150>] ? do_scsi_scan_host+0x90/0x90
- [<ffffffff810975b6>] kthread+0xa6/0xb0
- [<ffffffff817db154>] kernel_thread_helper+0x4/0x10
- [<ffffffff81066430>] ? finish_task_switch+0x80/0x110
- [<ffffffff817d9c04>] ? retint_restore_args+0xe/0xe
- [<ffffffff81097510>] ? __kthread_init_worker+0x70/0x70
- [<ffffffff817db150>] ? gs_change+0xb/0xb
-
-Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows:
+Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows::
 
 	if (rcu_dereference(ioc->ioc_data) == cic) {
 
@@ -70,7 +75,7 @@ case.  Instead, we hold three locks, one of which might be RCU related.
 And maybe that lock really does protect this reference.  If so, the fix
 is to inform RCU, perhaps by changing __cfq_exit_single_io_context() to
 take the struct request_queue "q" from cfq_exit_queue() as an argument,
-which would permit us to invoke rcu_dereference_protected as follows:
+which would permit us to invoke rcu_dereference_protected as follows::
 
 	if (rcu_dereference_protected(ioc->ioc_data,
 				      lockdep_is_held(&q->queue_lock)) == cic) {
@@ -85,7 +90,7 @@ On the other hand, perhaps we really do need an RCU read-side critical
 section.  In this case, the critical section must span the use of the
 return value from rcu_dereference(), or at least until there is some
 reference count incremented or some such.  One way to handle this is to
-add rcu_read_lock() and rcu_read_unlock() as follows:
+add rcu_read_lock() and rcu_read_unlock() as follows::
 
 	rcu_read_lock();
 	if (rcu_dereference(ioc->ioc_data) == cic) {
@@ -102,7 +107,7 @@ above lockdep-RCU splat.
 But in this particular case, we don't actually dereference the pointer
 returned from rcu_dereference().  Instead, that pointer is just compared
 to the cic pointer, which means that the rcu_dereference() can be replaced
-by rcu_access_pointer() as follows:
+by rcu_access_pointer() as follows::
 
 	if (rcu_access_pointer(ioc->ioc_data) == cic) {
 
-- 
2.25.2

[PATCH 03/10] docs: RCU: convert lockdep.txt to ReST

[Mauro Carvalho Chehab]

- Add a SPDX header;
- Adjust document title;
- Mark literal blocks as such;
- Add it to RCU/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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%)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 430a37132b2c..fa7a2a8949b7 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -11,6 +11,7 @@ RCU concepts
 
    arrayRCU
    checklist
+   lockdep
    lockdep-splat
    rcubarrier
    rcu_dereference
diff --git a/Documentation/RCU/lockdep.txt b/Documentation/RCU/lockdep.rst
similarity index 96%
rename from Documentation/RCU/lockdep.txt
rename to Documentation/RCU/lockdep.rst
index 89db949eeca0..f1fc8ae3846a 100644
--- a/Documentation/RCU/lockdep.txt
+++ b/Documentation/RCU/lockdep.rst
@@ -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,
-- 
2.25.2

[PATCH 04/10] docs: RCU: convert rculist_nulls.txt to ReST

[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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index fa7a2a8949b7..577a47e27f5d 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -17,6 +17,7 @@ RCU concepts
    rcu_dereference
    whatisRCU
    rcu
+   rculist_nulls
    listRCU
    NMI-RCU
    UP
diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
new file mode 100644
index 000000000000..d40374221d69
--- /dev/null
+++ b/Documentation/RCU/rculist_nulls.rst
@@ -0,0 +1,194 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================================
+Using RCU hlist_nulls to protect list and objects
+=================================================
+
+This section describes how to use hlist_nulls to
+protect read-mostly linked lists and
+objects using SLAB_TYPESAFE_BY_RCU allocations.
+
+Please read the basics in Documentation/RCU/listRCU.rst
+
+Using special makers (called 'nulls') is a convenient way
+to solve following problem :
+
+A typical RCU linked list managing objects which are
+allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can
+use following algos :
+
+1) Lookup algo
+--------------
+
+::
+
+  rcu_read_lock()
+  begin:
+  obj = lockless_lookup(key);
+  if (obj) {
+    if (!try_get_ref(obj)) // might fail for free objects
+      goto begin;
+    /*
+    * Because a writer could delete object, and a writer could
+    * reuse these object before the RCU grace period, we
+    * must check key after getting the reference on object
+    */
+    if (obj->key != key) { // not the object we expected
+      put_ref(obj);
+      goto begin;
+    }
+  }
+  rcu_read_unlock();
+
+Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu()
+but a version with an additional memory barrier (smp_rmb())
+
+::
+
+  lockless_lookup(key)
+  {
+    struct hlist_node *node, *next;
+    for (pos = rcu_dereference((head)->first);
+        pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
+        ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
+        pos = rcu_dereference(next))
+      if (obj->key == key)
+        return obj;
+    return NULL;
+  }
+
+And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb()::
+
+  struct hlist_node *node;
+  for (pos = rcu_dereference((head)->first);
+        pos && ({ prefetch(pos->next); 1; }) &&
+        ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
+        pos = rcu_dereference(pos->next))
+   if (obj->key == key)
+     return obj;
+  return NULL;
+
+Quoting Corey Minyard::
+
+  "If the object is moved from one list to another list in-between the
+  time the hash is calculated and the next field is accessed, and the
+  object has moved to the end of a new list, the traversal will not
+  complete properly on the list it should have, since the object will
+  be on the end of the new list and there's not a way to tell it's on a
+  new list and restart the list traversal. I think that this can be
+  solved by pre-fetching the "next" field (with proper barriers) before
+  checking the key."
+
+2) Insert algo
+--------------
+
+We need to make sure a reader cannot read the new 'obj->obj_next' value
+and previous value of 'obj->key'. Or else, an item could be deleted
+from a chain, and inserted into another chain. If new chain was empty
+before the move, 'next' pointer is NULL, and lockless reader can
+not detect it missed following items in original chain.
+
+::
+
+  /*
+  * Please note that new inserts are done at the head of list,
+  * not in the middle or end.
+  */
+  obj = kmem_cache_alloc(...);
+  lock_chain(); // typically a spin_lock()
+  obj->key = key;
+  /*
+  * we need to make sure obj->key is updated before obj->next
+  * or obj->refcnt
+  */
+  smp_wmb();
+  atomic_set(&obj->refcnt, 1);
+  hlist_add_head_rcu(&obj->obj_node, list);
+  unlock_chain(); // typically a spin_unlock()
+
+
+3) Remove algo
+--------------
+Nothing special here, we can use a standard RCU hlist deletion.
+But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused
+very very fast (before the end of RCU grace period)
+
+::
+
+  if (put_last_reference_on(obj) {
+    lock_chain(); // typically a spin_lock()
+    hlist_del_init_rcu(&obj->obj_node);
+    unlock_chain(); // typically a spin_unlock()
+    kmem_cache_free(cachep, obj);
+  }
+
+
+
+--------------------------------------------------------------------------
+
+With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
+and extra smp_wmb() in insert function.
+
+For example, if we choose to store the slot number as the 'nulls'
+end-of-list marker for each slot of the hash table, we can detect
+a race (some writer did a delete and/or a move of an object
+to another chain) checking the final 'nulls' value if
+the lookup met the end of chain. If final 'nulls' value
+is not the slot number, then we must restart the lookup at
+the beginning. If the object was moved to the same chain,
+then the reader doesn't care : It might eventually
+scan the list again without harm.
+
+
+1) lookup algo
+--------------
+
+::
+
+  head = &table[slot];
+  rcu_read_lock();
+  begin:
+  hlist_nulls_for_each_entry_rcu(obj, node, head, member) {
+    if (obj->key == key) {
+      if (!try_get_ref(obj)) // might fail for free objects
+        goto begin;
+      if (obj->key != key) { // not the object we expected
+        put_ref(obj);
+        goto begin;
+      }
+    goto out;
+  }
+  /*
+  * if the nulls value we got at the end of this lookup is
+  * not the expected one, we must restart lookup.
+  * We probably met an item that was moved to another chain.
+  */
+  if (get_nulls_value(node) != slot)
+  goto begin;
+  obj = NULL;
+
+  out:
+  rcu_read_unlock();
+
+2) Insert function
+------------------
+
+::
+
+  /*
+  * Please note that new inserts are done at the head of list,
+  * not in the middle or end.
+  */
+  obj = kmem_cache_alloc(cachep);
+  lock_chain(); // typically a spin_lock()
+  obj->key = key;
+  /*
+  * changes to obj->key must be visible before refcnt one
+  */
+  smp_wmb();
+  atomic_set(&obj->refcnt, 1);
+  /*
+  * insert obj in RCU way (readers might be traversing chain)
+  */
+  hlist_nulls_add_head_rcu(&obj->obj_node, list);
+  unlock_chain(); // typically a spin_unlock()
diff --git a/Documentation/RCU/rculist_nulls.txt b/Documentation/RCU/rculist_nulls.txt
deleted file mode 100644
index 23f115dc87cf..000000000000
--- a/Documentation/RCU/rculist_nulls.txt
+++ /dev/null
@@ -1,172 +0,0 @@
-Using hlist_nulls to protect read-mostly linked lists and
-objects using SLAB_TYPESAFE_BY_RCU allocations.
-
-Please read the basics in Documentation/RCU/listRCU.rst
-
-Using special makers (called 'nulls') is a convenient way
-to solve following problem :
-
-A typical RCU linked list managing objects which are
-allocated with SLAB_TYPESAFE_BY_RCU kmem_cache can
-use following algos :
-
-1) Lookup algo
---------------
-rcu_read_lock()
-begin:
-obj = lockless_lookup(key);
-if (obj) {
-  if (!try_get_ref(obj)) // might fail for free objects
-    goto begin;
-  /*
-   * Because a writer could delete object, and a writer could
-   * reuse these object before the RCU grace period, we
-   * must check key after getting the reference on object
-   */
-  if (obj->key != key) { // not the object we expected
-     put_ref(obj);
-     goto begin;
-   }
-}
-rcu_read_unlock();
-
-Beware that lockless_lookup(key) cannot use traditional hlist_for_each_entry_rcu()
-but a version with an additional memory barrier (smp_rmb())
-
-lockless_lookup(key)
-{
-   struct hlist_node *node, *next;
-   for (pos = rcu_dereference((head)->first);
-          pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
-          ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
-          pos = rcu_dereference(next))
-      if (obj->key == key)
-         return obj;
-   return NULL;
-
-And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb() :
-
-   struct hlist_node *node;
-   for (pos = rcu_dereference((head)->first);
-		pos && ({ prefetch(pos->next); 1; }) &&
-		({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
-		pos = rcu_dereference(pos->next))
-      if (obj->key == key)
-         return obj;
-   return NULL;
-}
-
-Quoting Corey Minyard :
-
-"If the object is moved from one list to another list in-between the
- time the hash is calculated and the next field is accessed, and the
- object has moved to the end of a new list, the traversal will not
- complete properly on the list it should have, since the object will
- be on the end of the new list and there's not a way to tell it's on a
- new list and restart the list traversal.  I think that this can be
- solved by pre-fetching the "next" field (with proper barriers) before
- checking the key."
-
-2) Insert algo :
-----------------
-
-We need to make sure a reader cannot read the new 'obj->obj_next' value
-and previous value of 'obj->key'. Or else, an item could be deleted
-from a chain, and inserted into another chain. If new chain was empty
-before the move, 'next' pointer is NULL, and lockless reader can
-not detect it missed following items in original chain.
-
-/*
- * Please note that new inserts are done at the head of list,
- * not in the middle or end.
- */
-obj = kmem_cache_alloc(...);
-lock_chain(); // typically a spin_lock()
-obj->key = key;
-/*
- * we need to make sure obj->key is updated before obj->next
- * or obj->refcnt
- */
-smp_wmb();
-atomic_set(&obj->refcnt, 1);
-hlist_add_head_rcu(&obj->obj_node, list);
-unlock_chain(); // typically a spin_unlock()
-
-
-3) Remove algo
---------------
-Nothing special here, we can use a standard RCU hlist deletion.
-But thanks to SLAB_TYPESAFE_BY_RCU, beware a deleted object can be reused
-very very fast (before the end of RCU grace period)
-
-if (put_last_reference_on(obj) {
-   lock_chain(); // typically a spin_lock()
-   hlist_del_init_rcu(&obj->obj_node);
-   unlock_chain(); // typically a spin_unlock()
-   kmem_cache_free(cachep, obj);
-}
-
-
-
---------------------------------------------------------------------------
-With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
-and extra smp_wmb() in insert function.
-
-For example, if we choose to store the slot number as the 'nulls'
-end-of-list marker for each slot of the hash table, we can detect
-a race (some writer did a delete and/or a move of an object
-to another chain) checking the final 'nulls' value if
-the lookup met the end of chain. If final 'nulls' value
-is not the slot number, then we must restart the lookup at
-the beginning. If the object was moved to the same chain,
-then the reader doesn't care : It might eventually
-scan the list again without harm.
-
-
-1) lookup algo
-
- head = &table[slot];
- rcu_read_lock();
-begin:
- hlist_nulls_for_each_entry_rcu(obj, node, head, member) {
-   if (obj->key == key) {
-      if (!try_get_ref(obj)) // might fail for free objects
-         goto begin;
-      if (obj->key != key) { // not the object we expected
-         put_ref(obj);
-         goto begin;
-      }
-  goto out;
- }
-/*
- * if the nulls value we got at the end of this lookup is
- * not the expected one, we must restart lookup.
- * We probably met an item that was moved to another chain.
- */
- if (get_nulls_value(node) != slot)
-   goto begin;
- obj = NULL;
-
-out:
- rcu_read_unlock();
-
-2) Insert function :
---------------------
-
-/*
- * Please note that new inserts are done at the head of list,
- * not in the middle or end.
- */
-obj = kmem_cache_alloc(cachep);
-lock_chain(); // typically a spin_lock()
-obj->key = key;
-/*
- * changes to obj->key must be visible before refcnt one
- */
-smp_wmb();
-atomic_set(&obj->refcnt, 1);
-/*
- * insert obj in RCU way (readers might be traversing chain)
- */
-hlist_nulls_add_head_rcu(&obj->obj_node, list);
-unlock_chain(); // typically a spin_unlock()
diff --git a/include/linux/rculist_nulls.h b/include/linux/rculist_nulls.h
index 9670b54b484a..ff3e94779e73 100644
--- a/include/linux/rculist_nulls.h
+++ b/include/linux/rculist_nulls.h
@@ -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();}),							\
diff --git a/net/core/sock.c b/net/core/sock.c
index 90509c37d291..da7eb3f5c03e 100644
--- a/net/core/sock.c
+++ b/net/core/sock.c
@@ -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);
-- 
2.25.2

[PATCH 05/10] docs: RCU: convert torture.txt to ReST

[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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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%)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 577a47e27f5d..5d5f9a1ab8f9 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -18,6 +18,7 @@ RCU concepts
    whatisRCU
    rcu
    rculist_nulls
+   torture
    listRCU
    NMI-RCU
    UP
diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.rst
similarity index 76%
rename from Documentation/RCU/torture.txt
rename to Documentation/RCU/torture.rst
index af712a3c5b6a..a90147713062 100644
--- a/Documentation/RCU/torture.txt
+++ b/Documentation/RCU/torture.rst
@@ -1,7 +1,12 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
 RCU Torture Test Operation
+==========================
 
 
 CONFIG_RCU_TORTURE_TEST
+=======================
 
 The CONFIG_RCU_TORTURE_TEST config option is available for all RCU
 implementations.  It creates an rcutorture kernel module that can
@@ -13,9 +18,10 @@ when the module is loaded, and stops when the module is unloaded.
 Module parameters are prefixed by "rcutorture." in
 Documentation/admin-guide/kernel-parameters.txt.
 
-OUTPUT
+Output
+======
 
-The statistics output is as follows:
+The statistics output is as follows::
 
 	rcu-torture:--- Start of test: nreaders=16 nfakewriters=4 stat_interval=30 verbose=0 test_no_idle_hz=1 shuffle_interval=3 stutter=5 irqreader=1 fqs_duration=0 fqs_holdoff=0 fqs_stutter=3 test_boost=1/0 test_boost_interval=7 test_boost_duration=4
 	rcu-torture: rtc:           (null) ver: 155441 tfle: 0 rta: 155441 rtaf: 8884 rtf: 155440 rtmbe: 0 rtbe: 0 rtbke: 0 rtbre: 0 rtbf: 0 rtb: 0 nt: 3055767
@@ -36,53 +42,53 @@ automatic determination as to whether RCU operated correctly.
 
 The entries are as follows:
 
-o	"rtc": The hexadecimal address of the structure currently visible
+*	"rtc": The hexadecimal address of the structure currently visible
 	to readers.
 
-o	"ver": The number of times since boot that the RCU writer task
+*	"ver": The number of times since boot that the RCU writer task
 	has changed the structure visible to readers.
 
-o	"tfle": If non-zero, indicates that the "torture freelist"
+*	"tfle": If non-zero, indicates that the "torture freelist"
 	containing structures to be placed into the "rtc" area is empty.
 	This condition is important, since it can fool you into thinking
 	that RCU is working when it is not.  :-/
 
-o	"rta": Number of structures allocated from the torture freelist.
+*	"rta": Number of structures allocated from the torture freelist.
 
-o	"rtaf": Number of allocations from the torture freelist that have
+*	"rtaf": Number of allocations from the torture freelist that have
 	failed due to the list being empty.  It is not unusual for this
 	to be non-zero, but it is bad for it to be a large fraction of
 	the value indicated by "rta".
 
-o	"rtf": Number of frees into the torture freelist.
+*	"rtf": Number of frees into the torture freelist.
 
-o	"rtmbe": A non-zero value indicates that rcutorture believes that
+*	"rtmbe": A non-zero value indicates that rcutorture believes that
 	rcu_assign_pointer() and rcu_dereference() are not working
 	correctly.  This value should be zero.
 
-o	"rtbe": A non-zero value indicates that one of the rcu_barrier()
+*	"rtbe": A non-zero value indicates that one of the rcu_barrier()
 	family of functions is not working correctly.
 
-o	"rtbke": rcutorture was unable to create the real-time kthreads
+*	"rtbke": rcutorture was unable to create the real-time kthreads
 	used to force RCU priority inversion.  This value should be zero.
 
-o	"rtbre": Although rcutorture successfully created the kthreads
+*	"rtbre": Although rcutorture successfully created the kthreads
 	used to force RCU priority inversion, it was unable to set them
 	to the real-time priority level of 1.  This value should be zero.
 
-o	"rtbf": The number of times that RCU priority boosting failed
+*	"rtbf": The number of times that RCU priority boosting failed
 	to resolve RCU priority inversion.
 
-o	"rtb": The number of times that rcutorture attempted to force
+*	"rtb": The number of times that rcutorture attempted to force
 	an RCU priority inversion condition.  If you are testing RCU
 	priority boosting via the "test_boost" module parameter, this
 	value should be non-zero.
 
-o	"nt": The number of times rcutorture ran RCU read-side code from
+*	"nt": The number of times rcutorture ran RCU read-side code from
 	within a timer handler.  This value should be non-zero only
 	if you specified the "irqreader" module parameter.
 
-o	"Reader Pipe": Histogram of "ages" of structures seen by readers.
+*	"Reader Pipe": Histogram of "ages" of structures seen by readers.
 	If any entries past the first two are non-zero, RCU is broken.
 	And rcutorture prints the error flag string "!!!" to make sure
 	you notice.  The age of a newly allocated structure is zero,
@@ -94,14 +100,14 @@ o	"Reader Pipe": Histogram of "ages" of structures seen by readers.
 	RCU.  If you want to see what it looks like when broken, break
 	it yourself.  ;-)
 
-o	"Reader Batch": Another histogram of "ages" of structures seen
+*	"Reader Batch": Another histogram of "ages" of structures seen
 	by readers, but in terms of counter flips (or batches) rather
 	than in terms of grace periods.  The legal number of non-zero
 	entries is again two.  The reason for this separate view is that
 	it is sometimes easier to get the third entry to show up in the
 	"Reader Batch" list than in the "Reader Pipe" list.
 
-o	"Free-Block Circulation": Shows the number of torture structures
+*	"Free-Block Circulation": Shows the number of torture structures
 	that have reached a given point in the pipeline.  The first element
 	should closely correspond to the number of structures allocated,
 	the second to the number that have been removed from reader view,
@@ -112,7 +118,7 @@ o	"Free-Block Circulation": Shows the number of torture structures
 
 Different implementations of RCU can provide implementation-specific
 additional information.  For example, Tree SRCU provides the following
-additional line:
+additional line::
 
 	srcud-torture: Tree SRCU per-CPU(idx=0): 0(35,-21) 1(-4,24) 2(1,1) 3(-26,20) 4(28,-47) 5(-9,4) 6(-10,14) 7(-14,11) T(1,6)
 
@@ -123,15 +129,15 @@ using a dynamically allocated srcu_struct (hence "srcud-" rather than
 "old" and "current" values to the underlying array, and is useful for
 debugging.  The final "T" entry contains the totals of the counters.
 
-
-USAGE ON SPECIFIC KERNEL BUILDS
+Usage on Specific Kernel Builds
+===============================
 
 It is sometimes desirable to torture RCU on a specific kernel build,
 for example, when preparing to put that kernel build into production.
 In that case, the kernel should be built with CONFIG_RCU_TORTURE_TEST=m
 so that the test can be started using modprobe and terminated using rmmod.
 
-For example, the following script may be used to torture RCU:
+For example, the following script may be used to torture RCU::
 
 	#!/bin/sh
 
@@ -148,7 +154,8 @@ two are self-explanatory, while the last indicates that while there
 were no RCU failures, CPU-hotplug problems were detected.
 
 
-USAGE ON MAINLINE KERNELS
+Usage on Mainline Kernels
+=========================
 
 When using rcutorture to test changes to RCU itself, it is often
 necessary to build a number of kernels in order to test that change
@@ -180,16 +187,16 @@ to Tree SRCU might run only the SRCU-N and SRCU-P scenarios using the
 --configs argument to kvm.sh as follows:  "--configs 'SRCU-N SRCU-P'".
 Large systems can run multiple copies of of the full set of scenarios,
 for example, a system with 448 hardware threads can run five instances
-of the full set concurrently.  To make this happen:
+of the full set concurrently.  To make this happen::
 
 	kvm.sh --cpus 448 --configs '5*CFLIST'
 
 Alternatively, such a system can run 56 concurrent instances of a single
-eight-CPU scenario:
+eight-CPU scenario::
 
 	kvm.sh --cpus 448 --configs '56*TREE04'
 
-Or 28 concurrent instances of each of two eight-CPU scenarios:
+Or 28 concurrent instances of each of two eight-CPU scenarios::
 
 	kvm.sh --cpus 448 --configs '28*TREE03 28*TREE04'
 
@@ -199,14 +206,14 @@ values for memory may require disabling the callback-flooding tests
 using the --bootargs parameter discussed below.
 
 Sometimes additional debugging is useful, and in such cases the --kconfig
-parameter to kvm.sh may be used, for example, "--kconfig 'CONFIG_KASAN=y'".
+parameter to kvm.sh may be used, for example, ``--kconfig 'CONFIG_KASAN=y'``.
 
 Kernel boot arguments can also be supplied, for example, to control
 rcutorture's module parameters.  For example, to test a change to RCU's
 CPU stall-warning code, use "--bootargs 'rcutorture.stall_cpu=30'".
 This will of course result in the scripting reporting a failure, namely
 the resuling RCU CPU stall warning.  As noted above, reducing memory may
-require disabling rcutorture's callback-flooding tests:
+require disabling rcutorture's callback-flooding tests::
 
 	kvm.sh --cpus 448 --configs '56*TREE04' --memory 128M \
 		--bootargs 'rcutorture.fwd_progress=0'
@@ -225,7 +232,7 @@ is listed at the end of the kvm.sh output, which you really should redirect
 to a file.  The build products and console output of each run is kept in
 tools/testing/selftests/rcutorture/res in timestamped directories.  A
 given directory can be supplied to kvm-find-errors.sh in order to have
-it cycle you through summaries of errors and full error logs.  For example:
+it cycle you through summaries of errors and full error logs.  For example::
 
 	tools/testing/selftests/rcutorture/bin/kvm-find-errors.sh \
 		tools/testing/selftests/rcutorture/res/2020.01.20-15.54.23
@@ -245,38 +252,42 @@ that was tested and any uncommitted changes in diff format.
 
 The most frequently used files in each per-scenario-run directory are:
 
-.config: This file contains the Kconfig options.
+.config:
+	This file contains the Kconfig options.
 
-Make.out: This contains build output for a specific scenario.
+Make.out:
+	This contains build output for a specific scenario.
 
-console.log: This contains the console output for a specific scenario.
+console.log:
+	This contains the console output for a specific scenario.
 	This file may be examined once the kernel has booted, but
 	it might not exist if the build failed.
 
-vmlinux: This contains the kernel, which can be useful with tools like
+vmlinux:
+	This contains the kernel, which can be useful with tools like
 	objdump and gdb.
 
 A number of additional files are available, but are less frequently used.
 Many are intended for debugging of rcutorture itself or of its scripting.
 
 As of v5.4, a successful run with the default set of scenarios produces
-the following summary at the end of the run on a 12-CPU system:
+the following summary at the end of the run on a 12-CPU system::
 
-SRCU-N ------- 804233 GPs (148.932/s) [srcu: g10008272 f0x0 ]
-SRCU-P ------- 202320 GPs (37.4667/s) [srcud: g1809476 f0x0 ]
-SRCU-t ------- 1122086 GPs (207.794/s) [srcu: g0 f0x0 ]
-SRCU-u ------- 1111285 GPs (205.794/s) [srcud: g1 f0x0 ]
-TASKS01 ------- 19666 GPs (3.64185/s) [tasks: g0 f0x0 ]
-TASKS02 ------- 20541 GPs (3.80389/s) [tasks: g0 f0x0 ]
-TASKS03 ------- 19416 GPs (3.59556/s) [tasks: g0 f0x0 ]
-TINY01 ------- 836134 GPs (154.84/s) [rcu: g0 f0x0 ] n_max_cbs: 34198
-TINY02 ------- 850371 GPs (157.476/s) [rcu: g0 f0x0 ] n_max_cbs: 2631
-TREE01 ------- 162625 GPs (30.1157/s) [rcu: g1124169 f0x0 ]
-TREE02 ------- 333003 GPs (61.6672/s) [rcu: g2647753 f0x0 ] n_max_cbs: 35844
-TREE03 ------- 306623 GPs (56.782/s) [rcu: g2975325 f0x0 ] n_max_cbs: 1496497
-CPU count limited from 16 to 12
-TREE04 ------- 246149 GPs (45.5831/s) [rcu: g1695737 f0x0 ] n_max_cbs: 434961
-TREE05 ------- 314603 GPs (58.2598/s) [rcu: g2257741 f0x2 ] n_max_cbs: 193997
-TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732
-CPU count limited from 16 to 12
-TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011
+    SRCU-N ------- 804233 GPs (148.932/s) [srcu: g10008272 f0x0 ]
+    SRCU-P ------- 202320 GPs (37.4667/s) [srcud: g1809476 f0x0 ]
+    SRCU-t ------- 1122086 GPs (207.794/s) [srcu: g0 f0x0 ]
+    SRCU-u ------- 1111285 GPs (205.794/s) [srcud: g1 f0x0 ]
+    TASKS01 ------- 19666 GPs (3.64185/s) [tasks: g0 f0x0 ]
+    TASKS02 ------- 20541 GPs (3.80389/s) [tasks: g0 f0x0 ]
+    TASKS03 ------- 19416 GPs (3.59556/s) [tasks: g0 f0x0 ]
+    TINY01 ------- 836134 GPs (154.84/s) [rcu: g0 f0x0 ] n_max_cbs: 34198
+    TINY02 ------- 850371 GPs (157.476/s) [rcu: g0 f0x0 ] n_max_cbs: 2631
+    TREE01 ------- 162625 GPs (30.1157/s) [rcu: g1124169 f0x0 ]
+    TREE02 ------- 333003 GPs (61.6672/s) [rcu: g2647753 f0x0 ] n_max_cbs: 35844
+    TREE03 ------- 306623 GPs (56.782/s) [rcu: g2975325 f0x0 ] n_max_cbs: 1496497
+    CPU count limited from 16 to 12
+    TREE04 ------- 246149 GPs (45.5831/s) [rcu: g1695737 f0x0 ] n_max_cbs: 434961
+    TREE05 ------- 314603 GPs (58.2598/s) [rcu: g2257741 f0x2 ] n_max_cbs: 193997
+    TREE07 ------- 167347 GPs (30.9902/s) [rcu: g1079021 f0x0 ] n_max_cbs: 478732
+    CPU count limited from 16 to 12
+    TREE09 ------- 752238 GPs (139.303/s) [rcu: g13075057 f0x0 ] n_max_cbs: 99011
diff --git a/Documentation/locking/locktorture.rst b/Documentation/locking/locktorture.rst
index 5bcb99ba7bd9..0b4bbe378bf1 100644
--- a/Documentation/locking/locktorture.rst
+++ b/Documentation/locking/locktorture.rst
@@ -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
diff --git a/MAINTAINERS b/MAINTAINERS
index ecf38ddd8962..ca534da466db 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -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 <josh@joshtriplett.org>
 L:	linux-kernel@vger.kernel.org
 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
diff --git a/kernel/rcu/rcutorture.c b/kernel/rcu/rcutorture.c
index efb792e13fca..8205295fc33e 100644
--- a/kernel/rcu/rcutorture.c
+++ b/kernel/rcu/rcutorture.c
@@ -7,7 +7,7 @@
  * Authors: Paul E. McKenney <paulmck@linux.ibm.com>
  *	  Josh Triplett <josh@joshtriplett.org>
  *
- * See also:  Documentation/RCU/torture.txt
+ * See also:  Documentation/RCU/torture.rst
  */
 
 #define pr_fmt(fmt) fmt
-- 
2.25.2

[PATCH 06/10] docs: RCU: convert rcuref.txt to ReST

[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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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%)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 5d5f9a1ab8f9..9a1d51f394dc 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -18,6 +18,7 @@ RCU concepts
    whatisRCU
    rcu
    rculist_nulls
+   rcuref
    torture
    listRCU
    NMI-RCU
diff --git a/Documentation/RCU/rcuref.txt b/Documentation/RCU/rcuref.rst
similarity index 50%
rename from Documentation/RCU/rcuref.txt
rename to Documentation/RCU/rcuref.rst
index 5e6429d66c24..b33aeb14fde3 100644
--- a/Documentation/RCU/rcuref.txt
+++ b/Documentation/RCU/rcuref.rst
@@ -1,4 +1,8 @@
-Reference-count design for elements of lists/arrays protected by RCU.
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================================================
+Reference-count design for elements of lists/arrays protected by RCU
+====================================================================
 
 
 Please note that the percpu-ref feature is likely your first
@@ -12,32 +16,33 @@ please read on.
 Reference counting on elements of lists which are protected by traditional
 reader/writer spinlocks or semaphores are straightforward:
 
-CODE LISTING A:
-1.				2.
-add()				search_and_reference()
-{				{
-    alloc_object		    read_lock(&list_lock);
-    ...				    search_for_element
-    atomic_set(&el->rc, 1);	    atomic_inc(&el->rc);
-    write_lock(&list_lock);	     ...
-    add_element			    read_unlock(&list_lock);
-    ...				    ...
-    write_unlock(&list_lock);	}
-}
+CODE LISTING A::
 
-3.					4.
-release_referenced()			delete()
-{					{
-    ...					    write_lock(&list_lock);
-    if(atomic_dec_and_test(&el->rc))	    ...
-	kfree(el);
-    ...					    remove_element
-}					    write_unlock(&list_lock);
- 					    ...
-					    if (atomic_dec_and_test(&el->rc))
-					        kfree(el);
-					    ...
-					}
+    1.					    2.
+    add()				    search_and_reference()
+    {					    {
+	alloc_object				read_lock(&list_lock);
+	...					search_for_element
+	atomic_set(&el->rc, 1);			atomic_inc(&el->rc);
+	write_lock(&list_lock);			 ...
+	add_element				read_unlock(&list_lock);
+	...					...
+	write_unlock(&list_lock);	   }
+    }
+
+    3.					    4.
+    release_referenced()		    delete()
+    {					    {
+	...					write_lock(&list_lock);
+	if(atomic_dec_and_test(&el->rc))	...
+	    kfree(el);
+	...					remove_element
+    }						write_unlock(&list_lock);
+						...
+						if (atomic_dec_and_test(&el->rc))
+						    kfree(el);
+						...
+					    }
 
 If this list/array is made lock free using RCU as in changing the
 write_lock() in add() and delete() to spin_lock() and changing read_lock()
@@ -46,34 +51,35 @@ search_and_reference() could potentially hold reference to an element which
 has already been deleted from the list/array.  Use atomic_inc_not_zero()
 in this scenario as follows:
 
-CODE LISTING B:
-1.					2.
-add()					search_and_reference()
-{					{
-    alloc_object			    rcu_read_lock();
-    ...					    search_for_element
-    atomic_set(&el->rc, 1);		    if (!atomic_inc_not_zero(&el->rc)) {
-    spin_lock(&list_lock);		        rcu_read_unlock();
-					        return FAIL;
-    add_element				    }
-    ...					    ...
-    spin_unlock(&list_lock);		    rcu_read_unlock();
-}					}
-3.					4.
-release_referenced()			delete()
-{					{
-    ...					    spin_lock(&list_lock);
-    if (atomic_dec_and_test(&el->rc))       ...
-        call_rcu(&el->head, el_free);       remove_element
-    ...                                     spin_unlock(&list_lock);
-} 					    ...
-					    if (atomic_dec_and_test(&el->rc))
-					        call_rcu(&el->head, el_free);
-					    ...
-					}
+CODE LISTING B::
+
+    1.					    2.
+    add()				    search_and_reference()
+    {					    {
+	alloc_object				rcu_read_lock();
+	...					search_for_element
+	atomic_set(&el->rc, 1);			if (!atomic_inc_not_zero(&el->rc)) {
+	spin_lock(&list_lock);			    rcu_read_unlock();
+						    return FAIL;
+	add_element				}
+	...					...
+	spin_unlock(&list_lock);		rcu_read_unlock();
+    }					    }
+    3.					    4.
+    release_referenced()		    delete()
+    {					    {
+	...					spin_lock(&list_lock);
+	if (atomic_dec_and_test(&el->rc))	...
+	    call_rcu(&el->head, el_free);	remove_element
+	...					spin_unlock(&list_lock);
+    }						...
+						if (atomic_dec_and_test(&el->rc))
+						    call_rcu(&el->head, el_free);
+						...
+					    }
 
 Sometimes, a reference to the element needs to be obtained in the
-update (write) stream.  In such cases, atomic_inc_not_zero() might be
+update (write) stream.	In such cases, atomic_inc_not_zero() might be
 overkill, since we hold the update-side spinlock.  One might instead
 use atomic_inc() in such cases.
 
@@ -82,39 +88,40 @@ search_and_reference() code path.  In such cases, the
 atomic_dec_and_test() may be moved from delete() to el_free()
 as follows:
 
-CODE LISTING C:
-1.					2.
-add()					search_and_reference()
-{					{
-    alloc_object			    rcu_read_lock();
-    ...					    search_for_element
-    atomic_set(&el->rc, 1);		    atomic_inc(&el->rc);
-    spin_lock(&list_lock);		    ...
+CODE LISTING C::
 
-    add_element				    rcu_read_unlock();
-    ...					}
-    spin_unlock(&list_lock);		4.
-}					delete()
-3.					{
-release_referenced()			    spin_lock(&list_lock);
-{					    ...
-    ...					    remove_element
-    if (atomic_dec_and_test(&el->rc))       spin_unlock(&list_lock);
-        kfree(el);			    ...
-    ...                                     call_rcu(&el->head, el_free);
-} 					    ...
-5.					}
-void el_free(struct rcu_head *rhp)
-{
-    release_referenced();
-}
+    1.					    2.
+    add()				    search_and_reference()
+    {					    {
+	alloc_object				rcu_read_lock();
+	...					search_for_element
+	atomic_set(&el->rc, 1);			atomic_inc(&el->rc);
+	spin_lock(&list_lock);			...
+
+	add_element				rcu_read_unlock();
+	...				    }
+	spin_unlock(&list_lock);	    4.
+    }					    delete()
+    3.					    {
+    release_referenced()			spin_lock(&list_lock);
+    {						...
+	...					remove_element
+	if (atomic_dec_and_test(&el->rc))	spin_unlock(&list_lock);
+	    kfree(el);				...
+	...					call_rcu(&el->head, el_free);
+    }						...
+    5.					    }
+    void el_free(struct rcu_head *rhp)
+    {
+	release_referenced();
+    }
 
 The key point is that the initial reference added by add() is not removed
 until after a grace period has elapsed following removal.  This means that
 search_and_reference() cannot find this element, which means that the value
 of el->rc cannot increase.  Thus, once it reaches zero, there are no
-readers that can or ever will be able to reference the element.  The
-element can therefore safely be freed.  This in turn guarantees that if
+readers that can or ever will be able to reference the element.	 The
+element can therefore safely be freed.	This in turn guarantees that if
 any reader finds the element, that reader may safely acquire a reference
 without checking the value of the reference counter.
 
@@ -130,21 +137,21 @@ the eventual invocation of kfree(), which is usually not a problem on
 modern computer systems, even the small ones.
 
 In cases where delete() can sleep, synchronize_rcu() can be called from
-delete(), so that el_free() can be subsumed into delete as follows:
+delete(), so that el_free() can be subsumed into delete as follows::
 
-4.
-delete()
-{
-    spin_lock(&list_lock);
-    ...
-    remove_element
-    spin_unlock(&list_lock);
-    ...
-    synchronize_rcu();
-    if (atomic_dec_and_test(&el->rc))
-    	kfree(el);
-    ...
-}
+    4.
+    delete()
+    {
+	spin_lock(&list_lock);
+	...
+	remove_element
+	spin_unlock(&list_lock);
+	...
+	synchronize_rcu();
+	if (atomic_dec_and_test(&el->rc))
+	    kfree(el);
+	...
+    }
 
 As additional examples in the kernel, the pattern in listing C is used by
 reference counting of struct pid, while the pattern in listing B is used by
-- 
2.25.2

[PATCH 07/10] docs: RCU: RTFP: fix bibtex entries

[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 <mchehab+huawei@kernel.org>
---
 Documentation/RCU/RTFP.txt | 98 +++++++++++++++++++-------------------
 1 file changed, 49 insertions(+), 49 deletions(-)

diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt
index 9bccf16736f7..6b93fbbfad19 100644
--- a/Documentation/RCU/RTFP.txt
+++ b/Documentation/RCU/RTFP.txt
@@ -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.
 }
 }
-- 
2.25.2

[PATCH 08/10] docs: RCU: convert RTFP.txt to ReST

[Mauro Carvalho Chehab]

The 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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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.rst

diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.bib
similarity index 85%
rename from Documentation/RCU/RTFP.txt
rename to Documentation/RCU/RTFP.bib
index 6b93fbbfad19..b5c6dc5239ae 100644
--- a/Documentation/RCU/RTFP.txt
+++ b/Documentation/RCU/RTFP.bib
@@ -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"
diff --git a/Documentation/RCU/RTFP.rst b/Documentation/RCU/RTFP.rst
new file mode 100644
index 000000000000..32a3668ed8ef
--- /dev/null
+++ b/Documentation/RCU/RTFP.rst
@@ -0,0 +1,593 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+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]_ [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]_.
+
+
+References
+==========
+
+.. [AjuJohn95] Aju John. Dynamic vnodes – design and implementation.
+    In USENIX Winter 1995, pages 11–23, New Orleans, LA, January 1995.
+    USENIX Association.
+    Available: https://www.usenix.org/publications/library/proceedings/neworl/full_papers/john.a
+    [Viewed October 1, 2010].
+
+.. [AlexeyGotsman2012VerifyGraceExtended] Alexey Gotsman, Noam Rinetzky,
+    and Hongseok Yang.
+    Verifying highly concurrent algorithms with grace (extended version).
+    http://software.imdea.org/~gotsman/papers/recycling-esop13-ext.pdf,
+    July 2012.
+
+.. [AlexeyGotsman2013ESOPRCU] Alexey Gotsman, Noam Rinetzky, and Hongseok Yang.
+    Verifying concurrent memory reclamation algorithms with grace.
+    In ESOP’13: European Symposium on Programming,
+    pages 249–269, Rome, Italy, 2013. Springer.
+
+.. [Andrews91textbook] Gregory R. Andrews.
+    Concurrent Programming, Principles, and Practices.
+    Benjamin Cummins, 1991.
+
+.. [Appavoo03a] J. Appavoo, K. Hui, C. A. N. Soules, R. W. Wisniewski,
+    D. M. Da Silva, O. Krieger, M. A. Auslander, D. J. Edelsohn, B. Gamsa,
+    G. R. Ganger, P. McKenney, M. Ostrowski, B. Rosenburg, M. Stumm,
+    and J. Xenidis.
+    Enabling autonomic behavior in systems software with hot swapping.
+    IBM Systems Journal,
+    42(1):60–76, January 2003.
+
+.. [Arcangeli03] Andrea Arcangeli, Mingming Cao, Paul E. McKenney, and Dipankar Sarma.
+    Using read-copy update techniques for System V IPC in the Linux 2.5 kernel.
+    In Proceedings of the 2003 USENIX Annual Technical Conference (FREENIX Track),
+    pages 297–310. USENIX Association, June 2003.
+
+.. [Cowan96a] Crispin Cowan, Tito Autrey, Charles Krasic, Calton Pu,
+    and Jonathan Walpole.
+    Fast concurrent dynamic linking for an adaptive operating system.
+    In International Conference on Configurable Distributed Systems (ICCDS’96),
+    page 108, Annapolis, MD, May 1996.
+
+.. [Dickins02a] Hugh Dickins. Use rcu for system-v ipc.
+    private communication, October 2002.
+
+.. [DinakarGuniguntala2008IBMSysJ] D. Guniguntala, P. E. McKenney, J. Triplett,
+    and J. Walpole.
+    The read-copy-update mechanism for supporting real-time applications
+    on shared-memory multiprocessor systems with Linux.
+    IBM Systems Journal, 47(2):221–236, May 2008.
+
+.. [Gamsa99] Ben Gamsa, Orran Krieger, Jonathan Appavoo, and Michael Stumm.
+    Tornado: Maximizing locality and concurrency in a shared memory
+    multiprocessor operating system.
+    In Proceedings of the 3 rd Symposium on Operating System Design
+    and Implementation, pages 87–100, New Orleans, LA, February 1999.
+
+.. [GuillermoVigueras2012RCUCrowd] Guillermo Vigueras, Juan M. Orduña, and
+    Miguel Lozano.
+    A Read-Copy Update based parallel server for distributed crowd simulations.
+    The Journal of Supercomputing, April 2012.
+
+.. [HMassalinPhD] H. Massalin.
+    Synthesis: An Efficient Implementation of Fundamental
+    Operating System Services.
+    PhD thesis, Columbia University, New York, NY, 1992.
+
+.. [HariKannan2009DynamicAnalysisRCU] Hari Kannan.
+    Ordering decoupled meta-data accesses in multiprocessors.
+    In MICRO 42: Proceedings of the 42nd Annual IEEE/ACM International
+    Symposium on Microarchitecture, pages 381–390, New York, NY, USA, 2009. ACM.
+
+.. [Hennessy89] James P. Hennessy, Damian L. Osisek, and Joseph W. Seigh II.
+    Passive serialization in a multitasking environment.
+    Technical Report US Patent 4,809,168 (lapsed),
+    US Patent and Trademark Office, Washington, DC, February 1989.
+
+.. [HerbertXu2010RCUResizeHash] Herbert Xu.
+    bridge: Add core igmp snooping support.
+    Available: http://thread.gmane.org/gmane.linux.network/153338
+    [Viewed June 9, 2014], February 2010.
+
+.. [HerlihyLM02] Maurice Herlihy, Victor Luchangco, and Mark Moir.
+    The repeat offender problem: A mechanism for supporting
+    dynamic-sized, lock-free data structures.
+    In Proceedings of 16 th International Symposium on Distributed Computing,
+    pages 339–353, October 2002.
+
+.. [Jacobson93] Van Jacobson. Avoid read-side locking via delayed free.
+    private communication, September 1993.
+
+.. [JamesMorris04b] James Morris.
+    Recent developments in SELinux kernel performance.
+    Available: http://www.livejournal.com/users/james_morris/2153.
+    html [Viewed December 10, 2004], December 2004.
+
+.. [JoshTriplett2009RPHash] Josh Triplett.
+    Scalable concurrent hash tables via relativistic programming.
+    Linux Plumbers Conference presentation, September 2009.
+
+.. [JoshTriplett2010RPHash] Josh Triplett, Paul E. McKenney, and Jonathan Walpole.
+    Scalable concurrent hash tables via relativistic programming.
+    ACM Operating Systems Review, 44(3), July 2010.
+
+.. [JoshTriplettPhD] Josh Triplett.
+    Relativistic Causal Ordering: A Memory Model for Scalable Concurrent
+    Data Structures. PhD thesis, Portland State University, 2012.
+
+.. [Kung80] H. T. Kung and Q. Lehman.
+    Concurrent manipulation of binary search trees.
+    ACM Transactions on Database Systems, 5(3):354–382, September1980.
+
+.. [Linder02a] Hanna Linder, Dipankar Sarma, and Maneesh Soni.
+    Scalability of the directory entry cache.
+    In Ottawa Linux Symposium, pages 289–300, June 2002.
+
+.. [LinusTorvalds2011Linux2:6:38:rc1:NPigginVFS] Linus Torvalds.
+    Linux 2.6.38-rc1.
+    Available: https://lkml.org/lkml/2011/1/18/322 [Viewed March 4, 2011],
+    January 2011.
+
+.. [MagedMichael04a] Maged M. Michael.
+    Hazard pointers: Safe memory reclamation for lock-free objects.
+    IEEE Transactions on Parallel and Distributed Systems,
+    15(6):491–504, June 2004.
+
+.. [Manber82] Udi Manber and Richard E. Ladner.
+    Concurrency control in a dynamic search structure.
+    Technical Report 82-01-01, Department of Computer Science,
+    University of Washington, Seattle, Washington, January 1982.
+
+.. [Manber84] Udi Manber and Richard E. Ladner.
+    Concurrency control in a dynamic search structure.
+    ACM Transactions on Database Systems,
+    9(3):439–455, September 1984.
+
+.. [MathieuDesnoyers2009URCU] Mathieu Desnoyers.
+    [RFC git tree] userspace RCU (urcu) for Linux.
+    http://lttng.org/urcu, February 2009.
+
+.. [MathieuDesnoyers2012URCU] Mathieu Desnoyers, Paul E. McKenney,
+    Alan Stern, Michel R. Dagenais, and Jonathan Walpole.
+    User-level implementations of read-copy update.
+    IEEE Transactions on Parallel and Distributed Systems, 23:375–382, 2012.
+
+.. [MathieuDesnoyersPhD] Mathieu Desnoyers.
+    Low-Impact Operating System Tracing.
+    PhD thesis, Ecole Polytechnique de Montréal, December 2009.
+    Available: http://www.lttng.org/pub/thesis/desnoyers-dissertation-2009-12.
+    [Viewed December 9, 2009].
+
+.. [McKenney01a] Paul E. McKenney, Jonathan Appavoo, Andi Kleen, Orran Krieger,
+    Rusty Russell, Dipankar Sarma, and Maneesh Soni.
+    Read-copy update. In Ottawa Linux Symposium, July 2001.
+    Available: http://www.linuxsymposium.org/2001/abstracts/readcopy.php
+    http://www.rdrop.com/users/paulmck/RCU/rclock_OLS.2001.05.01c.pdf
+    [Viewed June 23, 2004].
+
+.. [McKenney02a] Paul E. McKenney, Dipankar Sarma, Andrea Arcangeli, Andi Kleen,
+    Orran Krieger, and Rusty Russell.
+    Read-copy update.
+    In Ottawa Linux Symposium, pages 338–367, June 2002.
+    Available: http://www.linux.org.uk/~ajh/ols2002_proceedings.pdf.gz
+    [Viewed June 23, 2004].
+
+.. [McKenney03a] Paul E. McKenney. Using RCU in the Linux 2.5 kernel.
+    Linux Journal, 1(114):18–26, October 2003.
+    Available: http://www.linuxjournal.com/article/6993
+    [Viewed November 14, 2007].
+
+.. [McKenney04a] Paul E. McKenney, Dipankar Sarma, and Maneesh Soni.
+    Scaling dcache with RCU. Linux Journal, 1(118):38–46, January 2004.
+
+.. [McKenney04b] Paul E. McKenney.
+    RCU vs. locking performance on different CPUs.
+    In linux.conf.au, Adelaide, Australia, January 2004.
+    Available: http://www.linux.org.au/conf/2004/abstracts.html#90
+    http://www.rdrop.com/users/paulmck/RCU/lockperf.2004.01.17a.pdf
+    [Viewed June 23, 2004].
+
+.. [McKenney98] Paul E. McKenney and John D. Slingwine.
+    Read-copy update: Using execution history to solve concurrency problems.
+    In Parallel and Distributed Computing and Systems, pages 509–518,
+    Las Vegas, NV, October 1998.
+
+.. [Michael02a] Maged M. Michael.
+    Safe memory reclamation for dynamic lock-free objects using atomic reads
+    and writes. In Proceedings of the 21 st Annual ACM Symposium on
+    Principles of Distributed Computing, pages 21–30, August 2002.
+
+.. [Michael02b] Maged M. Michael.
+    High performance dynamic lock-free hash tables and list-based sets.
+    In Proceedings of the 14 th Annual ACM Symposium on Parallel Algorithms
+    and Architecture, pages 73–82, August 2002.
+
+.. [MingmingCao2002IPCRCU] Mingming Cao. [patch]updated ipc lock patch.
+    Available: https://lkml.org/lkml/2002/10/24/262
+    [Viewed February 15, 2014], October 2002.
+
+.. [NeilBrown2011MeetTheLockers] Neil Brown. Meet the Lockers.
+    Available: http://lwn.net/Articles/453685/
+    [Viewed September 2, 2011], August 2011.
+
+.. [PaulMcKenney05a] Paul E. McKenney.
+    [RFC] RCU and CONFIG_PREEMPT_RT progress.
+    Available: http://lkml.org/lkml/2005/5/9/185
+    [Viewed May 13, 2005], May 2005.
+
+.. [PaulMcKenney05b] Paul E. McKenney and Dipankar Sarma.
+    Towards hard realtime response from the Linux kernel on SMP hardware.
+    In linux.conf.au 2005, Canberra, Australia, April 2005.
+    Available: http://www.rdrop.com/users/paulmck/RCU/realtimeRCU.2005.04.23a.pdf
+    [Viewed May 13, 2005].
+
+.. [PaulEMcKenney2006b] Paul E. McKenney, Dipankar Sarma, Ingo Molnar, and
+    Suparna Bhattacharya.
+    Extending RCU for realtime and embedded workloads.
+    In Ottawa Linux Symposium, pages v2 123–138, July 2006.
+    Available: http://www.linuxsymposium.org/2006/view_abstract.php?content_key=184
+    http://www.rdrop.com/users/paulmck/RCU/OLSrtRCU.2006.08.11a.pdf
+    [Viewed January 1, 2007].
+
+.. [PaulEMcKenney2006c] Paul E. McKenney. Sleepable RCU.
+    Available: http://lwn.net/Articles/202847/
+    Revised: http://www.rdrop.com/users/paulmck/RCU/srcu.2007.01.14a.pdf
+    [Viewed August 21, 2006], October 2006.
+
+.. [PaulEMcKenney2007PreemptibleRCU] Paul E. McKenney.
+    The design of preemptible read-copy-update.
+    Available: http://lwn.net/Articles/253651/
+    [Viewed October 25, 2007], October 2007.
+
+.. [PaulEMcKenney2007QRCUspin] Paul E. McKenney.
+    Using Promela and Spin to verify parallel algorithms.
+    Available: http://lwn.net/Articles/243851/
+    [Viewed September 8, 2007], August 2007.
+
+.. [PaulEMcKenney2007WhatIsRCUFundamentally] Paul E. McKenney and
+    Jonathan Walpole. What is RCU, fundamentally?
+    Available: http://lwn.net/Articles/262464/
+    [Viewed December 27, 2007], December 2007.
+
+.. [PaulEMcKenney2008HierarchicalRCU] Paul E. McKenney.
+    Hierarchical RCU. http: //lwn.net/Articles/305782/, November 2008.
+
+.. [PaulEMcKenney2008RCUOSR] Paul E. McKenney and Jonathan Walpole.
+    Introducing technology into the Linux kernel: a case study.
+    SIGOPS Oper. Syst. Rev., 42(5):4–17, 2008.
+
+.. [PaulEMcKenney2008WhatIsRCUAPI] Paul E. McKenney.
+    RCU part 3: the RCU API.
+    Available: http://lwn.net/Articles/264090/
+    [Viewed January 10, 2008], January 2008.
+
+.. [PaulEMcKenney2008WhatIsRCUUsage] Paul E. McKenney.
+    What is RCU? part 2: Usage.
+    Available: http://lwn.net/Articles/263130/
+    [Viewed January 4, 2008], January 2008.
+
+.. [PaulEMcKenney2009BloatWatchRCU] Paul E. McKenney.
+    Re: [patch fyi] rcu: the bloatwatch edition.
+    Available: http://lkml.org/lkml/2009/1/14/449
+    [Viewed January 15, 2009], January 2009.
+
+.. [PaulEMcKenney2009MaliciousURCU] Paul E. McKenney.
+    Using a malicious user-level RCU to torture RCU-based algorithms.
+    In linux.conf.au 2009, Hobart, Australia, January 2009.
+    Available: http://www.rdrop.com/users/paulmck/RCU/urcutorture.2009.01.22a.pdf
+    [Viewed February 2, 2009].
+
+.. [PaulEMcKenney2009expeditedRCU] Paul E. McKenney.
+    [PATCH -tip 0/3] expedited ’big hammer’ RCU grace periods.
+    Available: http://lkml.org/lkml/2009/6/25/306 [Viewed August 16, 2009],
+    June 2009.
+
+.. [PaulEMcKenney2010LockdepRCU] Paul E. McKenney. Lockdep-RCU.
+    https://lwn.net/Articles/371986/, February 2010.
+
+.. [PaulEMcKenney2010RCUAPI] Paul E. McKenney. The RCU API, 2010 edition.
+    http://lwn.net/Articles/418853/, December 2010.
+
+.. [PaulEMcKenney2010SimpleOptRCU] Paul E. McKenney.
+    Simplicity through optimization.
+    In linux.conf.au 2010, Wellington, New Zealand, January 2010.
+    Available: http://www.rdrop.com/users/paulmck/RCU/SimplicityThruOptimization.2010.01.21f.pdf
+    [Viewed October 10, 2010].
+
+.. [PaulEMcKenney2011RCU3.0trainwreck] Paul E. McKenney.
+    3.0 and RCU: what went wrong. http://lwn.net/Articles/453002/, July 2011.
+
+.. [PaulEdwardMcKenneyPhD] Paul E. McKenney.
+    Exploiting Deferred Destruction: An Analysis of Read-Copy-Update
+    Techniques in Operating System Kernels. PhD thesis,
+    OGI School of Science and Engineering at Oregon Health
+    and Sciences University, 2004.
+
+.. [PhilHoward2011RCUTMRBTree] Philip W. Howard and Jonathan Walpole.
+    A relativistic enhancement to software transactional memory.
+    In Proceedings of the 3rd USENIX conference on Hot topics in parallelism,
+    HotPar’11, pages 1–6, Berkeley, CA, USA, 2011. USENIX Association.
+
+.. [Pu95a] Calton Pu, Tito Autrey, Andrew Black, Charles Consel, Crispin Cowan,
+    Jon Inouye, Lakshmi Kethana, Jonathan Walpole, and Ke Zhang.
+    Optimistic incremental specialization: Streamlining a commercial,
+    operating system.
+    In 15 the ACM Symposium on Operating Systems Principles (SOSP’95),
+    pages 314–321, Copper Mountain, CO, December 1995.
+
+.. [Pugh90] William Pugh. Concurrent maintenance of skip lists.
+    Technical Report CS-TR-2222.1,
+    Institute of Advanced Computer Science Studies,
+    Department of Computer Science, University of Maryland,
+    College Park, Maryland, June 1990.
+
+.. [RichardRashid87a] Richard Rashid, Avadis Tevanian, Michael Young,
+    David Golub,Robert Baron, David Black, William Bolosky, and Jonathan Chew.
+    Machine-independent virtual memory management for paged uniprocessor
+    and multiprocessor architectures. In 2 nd Symposium on Architectural
+    Support for Programming Languages and Operating Systems,
+    pages 31–39, Palo Alto, CA, October 1987.
+    Association for Computing Machinery.
+    Available: http://www.cse.ucsc.edu/~randal/221/rashid-machvm.pdf
+    [Viewed February 17, 2005].
+
+.. [RobertOlsson2006a] Robert Olsson and Stefan Nilsson.
+    TRASH: A dynamic LC-trie and hash data structure.
+    http://www.nada.kth.se/~snilsson/publications/TRASH/trash.pdf, August 2006.
+
+.. [RustyRussell2000a] Rusty Russell. Re: modular net drivers.
+    Available: http://oss.sgi.com/projects/netdev/archive/2000-06/msg00250.html
+    [Viewed April 10, 2006], June 2000.
+
+.. [RustyRussell2000b] Rusty Russell. Re: modular net drivers.
+    Available: http://oss.sgi.com/projects/netdev/archive/2000-06/msg00254.html
+    [Viewed April 10, 2006], June 2000.
+
+.. [Sarma04c] Dipankar Sarma and Paul E. McKenney.
+    Making RCU safe for deep sub-millisecond response realtime applications.
+    In Proceedings of the 2004 USENIX Annual Technical Conference
+    (FREENIX Track), pages 182–191. USENIX Association, June 2004.
+
+.. [Seyster:2011:RFA:2075416.2075425] Justin Seyster, Prabakar Radhakrishnan,
+    Samriti Katoch, Abhinav Duggal, Scott D. Stoller, and Erez Zadok.
+    Redflag: a framework for analysis of kernel-level concurrency.
+    In Proceedings of the 11th international conference on Algorithms
+    and architectures for parallel processing - Volume Part I, ICA3PP’11,
+    pages 66–79, Berlin, Heidelberg, 2011. Springer-Verlag.
+
+.. [Slingwine95] John D. Slingwine and Paul E. McKenney.
+    Apparatus and method for achieving reduced overhead mutual exclusion
+    and maintaining coherency in a multiprocessor system utilizing execution
+    history and thread monitoring.
+    Technical Report US Patent 5,442,758, US Patent and Trademark Office,
+    Washington, DC, August 1995.
+
+.. [ThomasEHart2006a] Thomas E. Hart, Paul E. McKenney, and
+    Angela Demke Brown. Making lockless synchronization fast:
+    Performance implications of memory reclamation.
+    In 20 th IEEE International Parallel and Distributed Processing Symposium,
+    Rhodes, Greece, April 2006.
+    Available: http://www.rdrop.com/users/paulmck/RCU/hart_ipdps06.pdf
+    [Viewed April 28, 2008].
+
+.. [ThomasEHart2007a] Thomas E. Hart, Paul E. McKenney, Angela Demke Brown,
+    and Jonathan Walpole. Performance of memory reclamation for lockless
+    synchronization. J. Parallel Distrib. Comput., 67(12):1270–1285, 2007.
+
+.. [Triplett:2011:RPHash] Josh Triplett, Paul E. McKenney, and Jonathan Walpole.
+    Resizable, scalable, concurrent hash tables via relativistic programming.
+    In Proceedings of the 2011 USENIX Annual Technical Conference,
+    pages 145–158, Portland, OR USA, June 2011. The USENIX Association.
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 9a1d51f394dc..9a99db701e5d 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -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
diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 0e03c6ef3147..c8fb0b5531b6 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -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/).
-- 
2.25.2

[PATCH 09/10] docs: RCU: stallwarn.txt: convert it to ReST

[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.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 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%)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 9a99db701e5d..7b8a8b6bc94b 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -20,6 +20,7 @@ RCU concepts
    rculist_nulls
    rcuref
    torture
+   stallwarn
    listRCU
    NMI-RCU
    UP
diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.rst
similarity index 90%
rename from Documentation/RCU/stallwarn.txt
rename to Documentation/RCU/stallwarn.rst
index a360a8796710..08bc9aec4606 100644
--- a/Documentation/RCU/stallwarn.txt
+++ b/Documentation/RCU/stallwarn.rst
@@ -1,4 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
 Using RCU's CPU Stall Detector
+==============================
 
 This document first discusses what sorts of issues RCU's CPU stall
 detector can locate, and then discusses kernel parameters and Kconfig
@@ -7,39 +11,40 @@ this document explains the stall detector's "splat" format.
 
 
 What Causes RCU CPU Stall Warnings?
+===================================
 
 So your kernel printed an RCU CPU stall warning.  The next question is
 "What caused it?"  The following problems can result in RCU CPU stall
 warnings:
 
-o	A CPU looping in an RCU read-side critical section.
+-	A CPU looping in an RCU read-side critical section.
 
-o	A CPU looping with interrupts disabled.
+-	A CPU looping with interrupts disabled.
 
-o	A CPU looping with preemption disabled.
+-	A CPU looping with preemption disabled.
 
-o	A CPU looping with bottom halves disabled.
+-	A CPU looping with bottom halves disabled.
 
-o	For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel
+-	For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel
 	without invoking schedule().  If the looping in the kernel is
 	really expected and desirable behavior, you might need to add
 	some calls to cond_resched().
 
-o	Booting Linux using a console connection that is too slow to
+-	Booting Linux using a console connection that is too slow to
 	keep up with the boot-time console-message rate.  For example,
 	a 115Kbaud serial console can be -way- too slow to keep up
 	with boot-time message rates, and will frequently result in
 	RCU CPU stall warning messages.  Especially if you have added
 	debug printk()s.
 
-o	Anything that prevents RCU's grace-period kthreads from running.
+-	Anything that prevents RCU's grace-period kthreads from running.
 	This can result in the "All QSes seen" console-log message.
 	This message will include information on when the kthread last
 	ran and how often it should be expected to run.  It can also
-	result in the "rcu_.*kthread starved for" console-log message,
+	result in the ``rcu_.*kthread starved for`` console-log message,
 	which will include additional debugging information.
 
-o	A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might
+-	A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might
 	happen to preempt a low-priority task in the middle of an RCU
 	read-side critical section.   This is especially damaging if
 	that low-priority task is not permitted to run on any other CPU,
@@ -48,7 +53,7 @@ o	A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might
 	While the system is in the process of running itself out of
 	memory, you might see stall-warning messages.
 
-o	A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
+-	A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
 	is running at a higher priority than the RCU softirq threads.
 	This will prevent RCU callbacks from ever being invoked,
 	and in a CONFIG_PREEMPT_RCU kernel will further prevent
@@ -63,7 +68,7 @@ o	A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
 	can increase your system's context-switch rate and thus degrade
 	performance.
 
-o	A periodic interrupt whose handler takes longer than the time
+-	A periodic interrupt whose handler takes longer than the time
 	interval between successive pairs of interrupts.  This can
 	prevent RCU's kthreads and softirq handlers from running.
 	Note that certain high-overhead debugging options, for example
@@ -71,20 +76,20 @@ o	A periodic interrupt whose handler takes longer than the time
 	considerably longer than normal, which can in turn result in
 	RCU CPU stall warnings.
 
-o	Testing a workload on a fast system, tuning the stall-warning
+-	Testing a workload on a fast system, tuning the stall-warning
 	timeout down to just barely avoid RCU CPU stall warnings, and then
 	running the same workload with the same stall-warning timeout on a
 	slow system.  Note that thermal throttling and on-demand governors
 	can cause a single system to be sometimes fast and sometimes slow!
 
-o	A hardware or software issue shuts off the scheduler-clock
+-	A hardware or software issue shuts off the scheduler-clock
 	interrupt on a CPU that is not in dyntick-idle mode.  This
 	problem really has happened, and seems to be most likely to
 	result in RCU CPU stall warnings for CONFIG_NO_HZ_COMMON=n kernels.
 
-o	A bug in the RCU implementation.
+-	A bug in the RCU implementation.
 
-o	A hardware failure.  This is quite unlikely, but has occurred
+-	A hardware failure.  This is quite unlikely, but has occurred
 	at least once in real life.  A CPU failed in a running system,
 	becoming unresponsive, but not causing an immediate crash.
 	This resulted in a series of RCU CPU stall warnings, eventually
@@ -109,6 +114,7 @@ see include/trace/events/rcu.h.
 
 
 Fine-Tuning the RCU CPU Stall Detector
+======================================
 
 The rcuupdate.rcu_cpu_stall_suppress module parameter disables RCU's
 CPU stall detector, which detects conditions that unduly delay RCU grace
@@ -118,6 +124,7 @@ The stall detector's idea of what constitutes "unduly delayed" is
 controlled by a set of kernel configuration variables and cpp macros:
 
 CONFIG_RCU_CPU_STALL_TIMEOUT
+----------------------------
 
 	This kernel configuration parameter defines the period of time
 	that RCU will wait from the beginning of a grace period until it
@@ -137,6 +144,7 @@ CONFIG_RCU_CPU_STALL_TIMEOUT
 	/sys/module/rcupdate/parameters/rcu_cpu_stall_suppress.
 
 RCU_STALL_DELAY_DELTA
+---------------------
 
 	Although the lockdep facility is extremely useful, it does add
 	some overhead.  Therefore, under CONFIG_PROVE_RCU, the
@@ -145,6 +153,7 @@ RCU_STALL_DELAY_DELTA
 	macro, not a kernel configuration parameter.)
 
 RCU_STALL_RAT_DELAY
+-------------------
 
 	The CPU stall detector tries to make the offending CPU print its
 	own warnings, as this often gives better-quality stack traces.
@@ -155,6 +164,7 @@ RCU_STALL_RAT_DELAY
 	parameter.)
 
 rcupdate.rcu_task_stall_timeout
+-------------------------------
 
 	This boot/sysfs parameter controls the RCU-tasks stall warning
 	interval.  A value of zero or less suppresses RCU-tasks stall
@@ -168,9 +178,10 @@ rcupdate.rcu_task_stall_timeout
 
 
 Interpreting RCU's CPU Stall-Detector "Splats"
+==============================================
 
 For non-RCU-tasks flavors of RCU, when a CPU detects that it is stalling,
-it will print a message similar to the following:
+it will print a message similar to the following::
 
 	INFO: rcu_sched detected stalls on CPUs/tasks:
 	2-...: (3 GPs behind) idle=06c/0/0 softirq=1453/1455 fqs=0
@@ -223,7 +234,7 @@ an estimate of the total number of RCU callbacks queued across all CPUs
 (625 in this case).
 
 In kernels with CONFIG_RCU_FAST_NO_HZ, more information is printed
-for each CPU:
+for each CPU::
 
 	0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 softirq=82/543 last_accelerate: a345/d342 dyntick_enabled: 1
 
@@ -235,7 +246,7 @@ processing is enabled.
 
 If the grace period ends just as the stall warning starts printing,
 there will be a spurious stall-warning message, which will include
-the following:
+the following::
 
 	INFO: Stall ended before state dump start
 
@@ -248,7 +259,7 @@ which is overkill for this sort of problem.
 
 If all CPUs and tasks have passed through quiescent states, but the
 grace period has nevertheless failed to end, the stall-warning splat
-will include something like the following:
+will include something like the following::
 
 	All QSes seen, last rcu_preempt kthread activity 23807 (4297905177-4297881370), jiffies_till_next_fqs=3, root ->qsmask 0x0
 
@@ -261,7 +272,7 @@ which is way less than 23807.  Finally, the root rcu_node structure's
 
 If the relevant grace-period kthread has been unable to run prior to
 the stall warning, as was the case in the "All QSes seen" line above,
-the following additional line is printed:
+the following additional line is printed::
 
 	kthread starved for 23807 jiffies! g7075 f0x0 RCU_GP_WAIT_FQS(3) ->state=0x1 ->cpu=5
 
@@ -276,6 +287,7 @@ kthread last ran on CPU 5.
 
 
 Multiple Warnings From One Stall
+================================
 
 If a stall lasts long enough, multiple stall-warning messages will be
 printed for it.  The second and subsequent messages are printed at
@@ -285,9 +297,10 @@ of the stall and the first message.
 
 
 Stall Warnings for Expedited Grace Periods
+==========================================
 
 If an expedited grace period detects a stall, it will place a message
-like the following in dmesg:
+like the following in dmesg::
 
 	INFO: rcu_sched detected expedited stalls on CPUs/tasks: { 7-... } 21119 jiffies s: 73 root: 0x2/.
 
diff --git a/kernel/rcu/tree_stall.h b/kernel/rcu/tree_stall.h
index ae76bd329582..b899883a4247 100644
--- a/kernel/rcu/tree_stall.h
+++ b/kernel/rcu/tree_stall.h
@@ -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);
-- 
2.25.2

[PATCH 10/10] docs: RCU: rculist_nulls.rst: don't duplicate chapter names

[Mauro Carvalho Chehab]

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.

Fixes: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/RCU/rculist_nulls.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
index d40374221d69..a9fc774bc400 100644
--- a/Documentation/RCU/rculist_nulls.rst
+++ b/Documentation/RCU/rculist_nulls.rst
@@ -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.
 
-- 
2.25.2

Re: [PATCH 07/10] docs: RCU: RTFP: fix bibtex entries

[Paul E. McKenney]

On Tue, Apr 21, 2020 at 07:04:08PM +0200, Mauro Carvalho Chehab wrote:
> 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 <mchehab+huawei@kernel.org>

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

> ---
>  Documentation/RCU/RTFP.txt | 98 +++++++++++++++++++-------------------
>  1 file changed, 49 insertions(+), 49 deletions(-)
> 
> diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt
> index 9bccf16736f7..6b93fbbfad19 100644
> --- a/Documentation/RCU/RTFP.txt
> +++ b/Documentation/RCU/RTFP.txt
> @@ -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.
>  }
>  }
> -- 
> 2.25.2
> 

Re: [PATCH 07/10] docs: RCU: RTFP: fix bibtex entries

[Paul E. McKenney]

On Tue, Apr 21, 2020 at 10:43:29AM -0700, Paul E. McKenney wrote:
> On Tue, Apr 21, 2020 at 07:04:08PM +0200, Mauro Carvalho Chehab wrote:
> > 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 <mchehab+huawei@kernel.org>
> 
> 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?

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

> > ---
> >  Documentation/RCU/RTFP.txt | 98 +++++++++++++++++++-------------------
> >  1 file changed, 49 insertions(+), 49 deletions(-)
> > 
> > diff --git a/Documentation/RCU/RTFP.txt b/Documentation/RCU/RTFP.txt
> > index 9bccf16736f7..6b93fbbfad19 100644
> > --- a/Documentation/RCU/RTFP.txt
> > +++ b/Documentation/RCU/RTFP.txt
> > @@ -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.
> >  }
> >  }
> > -- 
> > 2.25.2
> > 

Re: [PATCH 00/10] Manually convert RCU text files to ReST format

[Paul E. McKenney]

On Tue, Apr 21, 2020 at 07:04:01PM +0200, Mauro Carvalho Chehab wrote:
> 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

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

> 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%)
> 
> -- 
> 2.25.2
> 
> 

Re: [PATCH 07/10] docs: RCU: RTFP: fix bibtex entries

[Mauro Carvalho Chehab]

Em Tue, 21 Apr 2020 10:52:25 -0700
"Paul E. McKenney" <paulmck@kernel.org> escreveu:

> On Tue, Apr 21, 2020 at 10:43:29AM -0700, Paul E. McKenney wrote:
> > On Tue, Apr 21, 2020 at 07:04:08PM +0200, Mauro Carvalho Chehab wrote:  
> > > 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 <mchehab+huawei@kernel.org>  
> > 
> > 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.

> > 
> > 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'.

> 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

Re: [PATCH 07/10] docs: RCU: RTFP: fix bibtex entries

[Paul E. McKenney]

On Tue, Apr 21, 2020 at 09:29:06PM +0200, Mauro Carvalho Chehab wrote:
> Em Tue, 21 Apr 2020 10:52:25 -0700
> "Paul E. McKenney" <paulmck@kernel.org> escreveu:
> 
> > On Tue, Apr 21, 2020 at 10:43:29AM -0700, Paul E. McKenney wrote:
> > > On Tue, Apr 21, 2020 at 07:04:08PM +0200, Mauro Carvalho Chehab wrote:  
> > > > 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 <mchehab+huawei@kernel.org>  
> > > 
> > > 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.
> 
> > > 
> > > 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'.

OK, that sounds decidedly non-trivial.  :-(

> > 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