[Linux-kernel-mentees] [PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST

[Linux-kernel-mentees] [PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST

[c0d1n61at3]

Convert RCU linked list and add TOC tree hook.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst    |   1 +
 Documentation/RCU/listRCU.txt  | 315 -------------------------------
 Documentation/RCU/list_rcu.rst | 335 +++++++++++++++++++++++++++++++++
 Documentation/RCU/rcu.rst      |   4 +-
 4 files changed, 338 insertions(+), 317 deletions(-)
 delete mode 100644 Documentation/RCU/listRCU.txt
 create mode 100644 Documentation/RCU/list_rcu.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 30d1f2f3133f..69efb36acf0a 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -8,6 +8,7 @@ RCU concepts
    :maxdepth: 1
 
    rcu
+   list_rcu
 
 .. only::  subproject and html
 
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
deleted file mode 100644
index adb5a3782846..000000000000
--- a/Documentation/RCU/listRCU.txt
+++ /dev/null
@@ -1,315 +0,0 @@
-Using RCU to Protect Read-Mostly Linked Lists
-
-
-One of the best applications of RCU is to protect read-mostly linked lists
-("struct list_head" in list.h).  One big advantage of this approach
-is that all of the required memory barriers are included for you in
-the list macros.  This document describes several applications of RCU,
-with the best fits first.
-
-
-Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
-
-The best applications are cases where, if reader-writer locking were
-used, the read-side lock would be dropped before taking any action
-based on the results of the search.  The most celebrated example is
-the routing table.  Because the routing table is tracking the state of
-equipment outside of the computer, it will at times contain stale data.
-Therefore, once the route has been computed, there is no need to hold
-the routing table static during transmission of the packet.  After all,
-you can hold the routing table static all you want, but that won't keep
-the external Internet from changing, and it is the state of the external
-Internet that really matters.  In addition, routing entries are typically
-added or deleted, rather than being modified in place.
-
-A straightforward example of this use of RCU may be found in the
-system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
-
-	static enum audit_state audit_filter_task(struct task_struct *tsk)
-	{
-		struct audit_entry *e;
-		enum audit_state   state;
-
-		read_lock(&auditsc_lock);
-		/* Note: audit_netlink_sem held by caller. */
-		list_for_each_entry(e, &audit_tsklist, list) {
-			if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
-				read_unlock(&auditsc_lock);
-				return state;
-			}
-		}
-		read_unlock(&auditsc_lock);
-		return AUDIT_BUILD_CONTEXT;
-	}
-
-Here the list is searched under the lock, but the lock is dropped before
-the corresponding value is returned.  By the time that this value is acted
-on, the list may well have been modified.  This makes sense, since if
-you are turning auditing off, it is OK to audit a few extra system calls.
-
-This means that RCU can be easily applied to the read side, as follows:
-
-	static enum audit_state audit_filter_task(struct task_struct *tsk)
-	{
-		struct audit_entry *e;
-		enum audit_state   state;
-
-		rcu_read_lock();
-		/* Note: audit_netlink_sem held by caller. */
-		list_for_each_entry_rcu(e, &audit_tsklist, list) {
-			if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
-				rcu_read_unlock();
-				return state;
-			}
-		}
-		rcu_read_unlock();
-		return AUDIT_BUILD_CONTEXT;
-	}
-
-The read_lock() and read_unlock() calls have become rcu_read_lock()
-and rcu_read_unlock(), respectively, and the list_for_each_entry() has
-become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
-insert the read-side memory barriers that are required on DEC Alpha CPUs.
-
-The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
-
-	static inline int audit_del_rule(struct audit_rule *rule,
-					 struct list_head *list)
-	{
-		struct audit_entry  *e;
-
-		write_lock(&auditsc_lock);
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				list_del(&e->list);
-				write_unlock(&auditsc_lock);
-				return 0;
-			}
-		}
-		write_unlock(&auditsc_lock);
-		return -EFAULT;		/* No matching rule */
-	}
-
-	static inline int audit_add_rule(struct audit_entry *entry,
-					 struct list_head *list)
-	{
-		write_lock(&auditsc_lock);
-		if (entry->rule.flags & AUDIT_PREPEND) {
-			entry->rule.flags &= ~AUDIT_PREPEND;
-			list_add(&entry->list, list);
-		} else {
-			list_add_tail(&entry->list, list);
-		}
-		write_unlock(&auditsc_lock);
-		return 0;
-	}
-
-Following are the RCU equivalents for these two functions:
-
-	static inline int audit_del_rule(struct audit_rule *rule,
-					 struct list_head *list)
-	{
-		struct audit_entry  *e;
-
-		/* Do not use the _rcu iterator here, since this is the only
-		 * deletion routine. */
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				list_del_rcu(&e->list);
-				call_rcu(&e->rcu, audit_free_rule);
-				return 0;
-			}
-		}
-		return -EFAULT;		/* No matching rule */
-	}
-
-	static inline int audit_add_rule(struct audit_entry *entry,
-					 struct list_head *list)
-	{
-		if (entry->rule.flags & AUDIT_PREPEND) {
-			entry->rule.flags &= ~AUDIT_PREPEND;
-			list_add_rcu(&entry->list, list);
-		} else {
-			list_add_tail_rcu(&entry->list, list);
-		}
-		return 0;
-	}
-
-Normally, the write_lock() and write_unlock() would be replaced by
-a spin_lock() and a spin_unlock(), but in this case, all callers hold
-audit_netlink_sem, so no additional locking is required.  The auditsc_lock
-can therefore be eliminated, since use of RCU eliminates the need for
-writers to exclude readers.  Normally, the write_lock() calls would
-be converted into spin_lock() calls.
-
-The list_del(), list_add(), and list_add_tail() primitives have been
-replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu().
-The _rcu() list-manipulation primitives add memory barriers that are
-needed on weakly ordered CPUs (most of them!).  The list_del_rcu()
-primitive omits the pointer poisoning debug-assist code that would
-otherwise cause concurrent readers to fail spectacularly.
-
-So, when readers can tolerate stale data and when entries are either added
-or deleted, without in-place modification, it is very easy to use RCU!
-
-
-Example 2: Handling In-Place Updates
-
-The system-call auditing code does not update auditing rules in place.
-However, if it did, reader-writer-locked code to do so might look as
-follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
-
-	static inline int audit_upd_rule(struct audit_rule *rule,
-					 struct list_head *list,
-					 __u32 newaction,
-					 __u32 newfield_count)
-	{
-		struct audit_entry  *e;
-		struct audit_newentry *ne;
-
-		write_lock(&auditsc_lock);
-		/* Note: audit_netlink_sem held by caller. */
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				e->rule.action = newaction;
-				e->rule.file_count = newfield_count;
-				write_unlock(&auditsc_lock);
-				return 0;
-			}
-		}
-		write_unlock(&auditsc_lock);
-		return -EFAULT;		/* No matching rule */
-	}
-
-The RCU version creates a copy, updates the copy, then replaces the old
-entry with the newly updated entry.  This sequence of actions, allowing
-concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
-
-	static inline int audit_upd_rule(struct audit_rule *rule,
-					 struct list_head *list,
-					 __u32 newaction,
-					 __u32 newfield_count)
-	{
-		struct audit_entry  *e;
-		struct audit_newentry *ne;
-
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
-				if (ne == NULL)
-					return -ENOMEM;
-				audit_copy_rule(&ne->rule, &e->rule);
-				ne->rule.action = newaction;
-				ne->rule.file_count = newfield_count;
-				list_replace_rcu(&e->list, &ne->list);
-				call_rcu(&e->rcu, audit_free_rule);
-				return 0;
-			}
-		}
-		return -EFAULT;		/* No matching rule */
-	}
-
-Again, this assumes that the caller holds audit_netlink_sem.  Normally,
-the reader-writer lock would become a spinlock in this sort of code.
-
-
-Example 3: Eliminating Stale Data
-
-The auditing examples above tolerate stale data, as do most algorithms
-that are tracking external state.  Because there is a delay from the
-time the external state changes before Linux becomes aware of the change,
-additional RCU-induced staleness is normally not a problem.
-
-However, there are many examples where stale data cannot be tolerated.
-One example in the Linux kernel is the System V IPC (see the ipc_lock()
-function in ipc/util.c).  This code checks a "deleted" flag under a
-per-entry spinlock, and, if the "deleted" flag is set, pretends that the
-entry does not exist.  For this to be helpful, the search function must
-return holding the per-entry spinlock, as ipc_lock() does in fact do.
-
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
-
-If the system-call audit module were to ever need to reject stale data,
-one way to accomplish this would be to add a "deleted" flag and a "lock"
-spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
-
-	static enum audit_state audit_filter_task(struct task_struct *tsk)
-	{
-		struct audit_entry *e;
-		enum audit_state   state;
-
-		rcu_read_lock();
-		list_for_each_entry_rcu(e, &audit_tsklist, list) {
-			if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
-				spin_lock(&e->lock);
-				if (e->deleted) {
-					spin_unlock(&e->lock);
-					rcu_read_unlock();
-					return AUDIT_BUILD_CONTEXT;
-				}
-				rcu_read_unlock();
-				return state;
-			}
-		}
-		rcu_read_unlock();
-		return AUDIT_BUILD_CONTEXT;
-	}
-
-Note that this example assumes that entries are only added and deleted.
-Additional mechanism is required to deal correctly with the
-update-in-place performed by audit_upd_rule().  For one thing,
-audit_upd_rule() would need additional memory barriers to ensure
-that the list_add_rcu() was really executed before the list_del_rcu().
-
-The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
-
-	static inline int audit_del_rule(struct audit_rule *rule,
-					 struct list_head *list)
-	{
-		struct audit_entry  *e;
-
-		/* Do not need to use the _rcu iterator here, since this
-		 * is the only deletion routine. */
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				spin_lock(&e->lock);
-				list_del_rcu(&e->list);
-				e->deleted = 1;
-				spin_unlock(&e->lock);
-				call_rcu(&e->rcu, audit_free_rule);
-				return 0;
-			}
-		}
-		return -EFAULT;		/* No matching rule */
-	}
-
-
-Summary
-
-Read-mostly list-based data structures that can tolerate stale data are
-the most amenable to use of RCU.  The simplest case is where entries are
-either added or deleted from the data structure (or atomically modified
-in place), but non-atomic in-place modifications can be handled by making
-a copy, updating the copy, then replacing the original with the copy.
-If stale data cannot be tolerated, then a "deleted" flag may be used
-in conjunction with a per-entry spinlock in order to allow the search
-function to reject newly deleted data.
-
-
-Answer to Quick Quiz
-	Why does the search function need to return holding the per-entry
-	lock for this deleted-flag technique to be helpful?
-
-	If the search function drops the per-entry lock before returning,
-	then the caller will be processing stale data in any case.  If it
-	is really OK to be processing stale data, then you don't need a
-	"deleted" flag.  If processing stale data really is a problem,
-	then you need to hold the per-entry lock across all of the code
-	that uses the value that was returned.
diff --git a/Documentation/RCU/list_rcu.rst b/Documentation/RCU/list_rcu.rst
new file mode 100644
index 000000000000..255c9e173fba
--- /dev/null
+++ b/Documentation/RCU/list_rcu.rst
@@ -0,0 +1,335 @@
+.. _list_rcu_doc:
+
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
+
+One of the best applications of RCU is to protect read-mostly linked lists
+(*struct list_head* in ``list.h``).  One big advantage of this approach
+is that all of the required memory barriers are included for you in
+the list macros.  This document describes several applications of RCU,
+with the best fits first.
+
+Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
+
+The best applications are cases where, if reader-writer locking were
+used, the read-side lock would be dropped before taking any action
+based on the results of the search.  The most celebrated example is
+the routing table.  Because the routing table is tracking the state of
+equipment outside of the computer, it will at times contain stale data.
+Therefore, once the route has been computed, there is no need to hold
+the routing table static during transmission of the packet.  After all,
+you can hold the routing table static all you want, but that won't keep
+the external Internet from changing, and it is the state of the external
+Internet that really matters.  In addition, routing entries are typically
+added or deleted, rather than being modified in place.
+
+A straightforward example of this use of RCU may be found in the
+system-call auditing support.  For example, a reader-writer locked
+implementation of *audit_filter_task()* might be as follows:
+
+.. code-block:: c
+
+   static enum audit_state audit_filter_task(struct task_struct *tsk)
+   {
+      struct audit_entry *e;
+      enum audit_state   state;
+
+      read_lock(&auditsc_lock);
+      /* Note: audit_netlink_sem held by caller. */
+      list_for_each_entry(e, &audit_tsklist, list) {
+         if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+            read_unlock(&auditsc_lock);
+            return state;
+         }
+      }
+      read_unlock(&auditsc_lock);
+      return AUDIT_BUILD_CONTEXT;
+   }
+
+Here the list is searched under the lock, but the lock is dropped before
+the corresponding value is returned.  By the time that this value is acted
+on, the list may well have been modified.  This makes sense, since if
+you are turning auditing off, it is OK to audit a few extra system calls.
+
+This means that RCU can be easily applied to the read side, as follows:
+
+.. code-block:: c
+
+   static enum audit_state audit_filter_task(struct task_struct *tsk)
+   {
+      struct audit_entry *e;
+      enum audit_state   state;
+
+      rcu_read_lock();
+      /* Note: audit_netlink_sem held by caller. */
+      list_for_each_entry_rcu(e, &audit_tsklist, list) {
+         if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+            rcu_read_unlock();
+            return state;
+         }
+      }
+      rcu_read_unlock();
+      return AUDIT_BUILD_CONTEXT;
+   }
+
+The *read_lock()* and *read_unlock()* calls have become *rcu_read_lock()*
+and *rcu_read_unlock()*, respectively, and the *list_for_each_entry()* has
+become *list_for_each_entry_rcu()*.  The *_rcu()* list-traversal primitives
+insert the read-side memory barriers that are required on DEC Alpha CPUs.
+
+The changes to the update side are also straightforward.  A reader-writer
+lock might be used as follows for deletion and insertion:
+
+.. code-block:: c
+
+   static inline int audit_del_rule(struct audit_rule *rule,
+                                    struct list_head *list)
+   {
+      struct audit_entry  *e;
+
+      write_lock(&auditsc_lock);
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            list_del(&e->list);
+            write_unlock(&auditsc_lock);
+            return 0;
+         }
+      }
+      write_unlock(&auditsc_lock);
+      return -EFAULT;   /* No matching rule */
+   }
+
+   static inline int audit_add_rule(struct audit_entry *entry,
+                                    struct list_head *list)
+   {
+      write_lock(&auditsc_lock);
+      if (entry->rule.flags & AUDIT_PREPEND) {
+         entry->rule.flags &= ~AUDIT_PREPEND;
+         list_add(&entry->list, list);
+      } else {
+         list_add_tail(&entry->list, list);
+      }
+      write_unlock(&auditsc_lock);
+      return 0;
+   }
+
+Following are the RCU equivalents for these two functions:
+
+.. code-block:: c
+
+   static inline int audit_del_rule(struct audit_rule *rule,
+                                    struct list_head *list)
+   {
+      struct audit_entry  *e;
+
+      /* Do not use the _rcu iterator here, since this is the only
+       * deletion routine. */
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            list_del_rcu(&e->list);
+            call_rcu(&e->rcu, audit_free_rule);
+            return 0;
+         }
+      }
+      return -EFAULT;   /* No matching rule */
+   }
+
+   static inline int audit_add_rule(struct audit_entry *entry,
+                                    struct list_head *list)
+   {
+      if (entry->rule.flags & AUDIT_PREPEND) {
+         entry->rule.flags &= ~AUDIT_PREPEND;
+         list_add_rcu(&entry->list, list);
+      } else {
+         list_add_tail_rcu(&entry->list, list);
+      }
+      return 0;
+   }
+
+Normally, the *write_lock()* and *write_unlock()* would be replaced by
+a *spin_lock()* and a *spin_unlock()*, but in this case, all callers hold
+*audit_netlink_sem*, so no additional locking is required.  The *auditsc_lock*
+can therefore be eliminated, since use of RCU eliminates the need for
+writers to exclude readers.  Normally, the *write_lock()* calls would
+be converted into *spin_lock()* calls.
+
+The *list_del()*, *list_add()*, and *list_add_tail()* primitives have been
+replaced by *list_del_rcu()*, *list_add_rcu()*, and *list_add_tail_rcu()*.
+The *_rcu()* list-manipulation primitives add memory barriers that are
+needed on weakly ordered CPUs (most of them!).  The *list_del_rcu()*
+primitive omits the pointer poisoning debug-assist code that would
+otherwise cause concurrent readers to fail spectacularly.
+
+So, when readers can tolerate stale data and when entries are either added
+or deleted, without in-place modification, it is very easy to use RCU!
+
+Example 2: Handling In-Place Updates
+------------------------------------
+
+The system-call auditing code does not update auditing rules in place.
+However, if it did, reader-writer-locked code to do so might look as
+follows (presumably, the field_count is only permitted to decrease,
+otherwise, the added fields would need to be filled in):
+
+.. code-block:: c
+
+   static inline int audit_upd_rule(struct audit_rule *rule,
+                                    struct list_head *list,
+                                    __u32 newaction,
+                                    __u32 newfield_count)
+   {
+      struct audit_entry  *e;
+      struct audit_newentry *ne;
+
+      write_lock(&auditsc_lock);
+      /* Note: audit_netlink_sem held by caller. */
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            e->rule.action = newaction;
+            e->rule.file_count = newfield_count;
+            write_unlock(&auditsc_lock);
+            return 0;
+         }
+      }
+      write_unlock(&auditsc_lock);
+      return -EFAULT;   /* No matching rule */
+   }
+
+The RCU version creates a copy, updates the copy, then replaces the old
+entry with the newly updated entry.  This sequence of actions, allowing
+concurrent reads while doing a copy to perform an update, is what gives
+RCU ("read-copy update") its name.  The RCU code is as follows:
+
+.. code-block:: c
+
+   static inline int audit_upd_rule(struct audit_rule *rule,
+                                    struct list_head *list,
+                                    __u32 newaction,
+                                    __u32 newfield_count)
+   {
+      struct audit_entry  *e;
+      struct audit_newentry *ne;
+
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
+            if (ne == NULL)
+               return -ENOMEM;
+            audit_copy_rule(&ne->rule, &e->rule);
+            ne->rule.action = newaction;
+            ne->rule.file_count = newfield_count;
+            list_replace_rcu(&e->list, &ne->list);
+            call_rcu(&e->rcu, audit_free_rule);
+            return 0;
+         }
+      }
+      return -EFAULT;   /* No matching rule */
+   }
+
+Again, this assumes that the caller holds audit_netlink_sem.  Normally,
+the reader-writer lock would become a spinlock in this sort of code.
+
+Example 3: Eliminating Stale Data
+
+The auditing examples above tolerate stale data, as do most algorithms
+that are tracking external state.  Because there is a delay from the
+time the external state changes before Linux becomes aware of the change,
+additional RCU-induced staleness is normally not a problem.
+
+However, there are many examples where stale data cannot be tolerated.
+One example in the Linux kernel is the System V IPC (see the *ipc_lock()*
+function in ``ipc/util.c``).  This code checks a *deleted* flag under a
+per-entry spinlock, and, if the *deleted* flag is set, pretends that the
+entry does not exist.  For this to be helpful, the search function must
+return holding the per-entry spinlock, as *ipc_lock()* does in fact do.
+
+Quick Quiz:  Why does the search function need to return holding the
+	per-entry lock for this deleted-flag technique to be helpful?
+
+:ref:`answer_quick_quiz`
+
+If the system-call audit module were to ever need to reject stale data,
+one way to accomplish this would be to add a *deleted* flag and a *lock*
+spinlock to the *audit_entry* structure, and modify *audit_filter_task()*
+as follows:
+
+.. code-block:: c
+
+   static enum audit_state audit_filter_task(struct task_struct *tsk)
+   {
+      struct audit_entry *e;
+      enum audit_state   state;
+
+      rcu_read_lock();
+      list_for_each_entry_rcu(e, &audit_tsklist, list) {
+         if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+            spin_lock(&e->lock);
+            if (e->deleted) {
+               spin_unlock(&e->lock);
+               rcu_read_unlock();
+               return AUDIT_BUILD_CONTEXT;
+            }
+            rcu_read_unlock();
+            return state;
+         }
+      }
+      rcu_read_unlock();
+      return AUDIT_BUILD_CONTEXT;
+   }
+
+Note that this example assumes that entries are only added and deleted.
+Additional mechanism is required to deal correctly with the
+update-in-place performed by *audit_upd_rule()*.  For one thing,
+*audit_upd_rule()* would need additional memory barriers to ensure
+that the *list_add_rcu()* was really executed before the *list_del_rcu()*.
+
+The *audit_del_rule()* function would need to set the *deleted*
+flag under the spinlock as follows:
+
+.. code-block:: c
+
+   static inline int audit_del_rule(struct audit_rule *rule,
+                                    struct list_head *list)
+   {
+      struct audit_entry  *e;
+
+      /* Do not need to use the _rcu iterator here, since this
+       * is the only deletion routine. */
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            spin_lock(&e->lock);
+            list_del_rcu(&e->list);
+            e->deleted = 1;
+            spin_unlock(&e->lock);
+            call_rcu(&e->rcu, audit_free_rule);
+            return 0;
+         }
+      }
+      return -EFAULT;   /* No matching rule */
+   }
+
+.. _answer_quick_quiz:
+
+Summary
+-------
+
+Read-mostly list-based data structures that can tolerate stale data are
+the most amenable to use of RCU.  The simplest case is where entries are
+either added or deleted from the data structure (or atomically modified
+in place), but non-atomic in-place modifications can be handled by making
+a copy, updating the copy, then replacing the original with the copy.
+If stale data cannot be tolerated, then a *deleted* flag may be used
+in conjunction with a per-entry spinlock in order to allow the search
+function to reject newly deleted data.
+
+Answer to Quick Quiz
+	Why does the search function need to return holding the per-entry
+	lock for this deleted-flag technique to be helpful?
+
+	If the search function drops the per-entry lock before returning,
+	then the caller will be processing stale data in any case.  If it
+	is really OK to be processing stale data, then you don't need a
+	"deleted" flag.  If processing stale data really is a problem,
+	then you need to hold the per-entry lock across all of the code
+	that uses the value that was returned.
diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index e95f023d6065..fec4a71e8b95 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -11,7 +11,7 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See listRCU.txt
+a grace period to elapse, then free the element.  See :ref:`list_rcu_doc`
 for more information on using RCU with linked lists.
 
 Frequently Asked Questions
@@ -67,7 +67,7 @@ Frequently Asked Questions
 
 - Why the name "RCU"?
 
-  "RCU" stands for "read-copy update".  listRCU.txt has
+  "RCU" stands for "read-copy update".  :ref:`list_rcu_doc` has
   more information on where this name came from, search for
   "read-copy update" to find it.
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST

[Jiunn Chang]

Convert RCU linked list and add TOC tree hook.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst    |   1 +
 Documentation/RCU/listRCU.txt  | 315 -------------------------------
 Documentation/RCU/list_rcu.rst | 335 +++++++++++++++++++++++++++++++++
 Documentation/RCU/rcu.rst      |   4 +-
 4 files changed, 338 insertions(+), 317 deletions(-)
 delete mode 100644 Documentation/RCU/listRCU.txt
 create mode 100644 Documentation/RCU/list_rcu.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 30d1f2f3133f..69efb36acf0a 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -8,6 +8,7 @@ RCU concepts
    :maxdepth: 1
 
    rcu
+   list_rcu
 
 .. only::  subproject and html
 
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
deleted file mode 100644
index adb5a3782846..000000000000
--- a/Documentation/RCU/listRCU.txt
+++ /dev/null
@@ -1,315 +0,0 @@
-Using RCU to Protect Read-Mostly Linked Lists
-
-
-One of the best applications of RCU is to protect read-mostly linked lists
-("struct list_head" in list.h).  One big advantage of this approach
-is that all of the required memory barriers are included for you in
-the list macros.  This document describes several applications of RCU,
-with the best fits first.
-
-
-Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
-
-The best applications are cases where, if reader-writer locking were
-used, the read-side lock would be dropped before taking any action
-based on the results of the search.  The most celebrated example is
-the routing table.  Because the routing table is tracking the state of
-equipment outside of the computer, it will at times contain stale data.
-Therefore, once the route has been computed, there is no need to hold
-the routing table static during transmission of the packet.  After all,
-you can hold the routing table static all you want, but that won't keep
-the external Internet from changing, and it is the state of the external
-Internet that really matters.  In addition, routing entries are typically
-added or deleted, rather than being modified in place.
-
-A straightforward example of this use of RCU may be found in the
-system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
-
-	static enum audit_state audit_filter_task(struct task_struct *tsk)
-	{
-		struct audit_entry *e;
-		enum audit_state   state;
-
-		read_lock(&auditsc_lock);
-		/* Note: audit_netlink_sem held by caller. */
-		list_for_each_entry(e, &audit_tsklist, list) {
-			if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
-				read_unlock(&auditsc_lock);
-				return state;
-			}
-		}
-		read_unlock(&auditsc_lock);
-		return AUDIT_BUILD_CONTEXT;
-	}
-
-Here the list is searched under the lock, but the lock is dropped before
-the corresponding value is returned.  By the time that this value is acted
-on, the list may well have been modified.  This makes sense, since if
-you are turning auditing off, it is OK to audit a few extra system calls.
-
-This means that RCU can be easily applied to the read side, as follows:
-
-	static enum audit_state audit_filter_task(struct task_struct *tsk)
-	{
-		struct audit_entry *e;
-		enum audit_state   state;
-
-		rcu_read_lock();
-		/* Note: audit_netlink_sem held by caller. */
-		list_for_each_entry_rcu(e, &audit_tsklist, list) {
-			if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
-				rcu_read_unlock();
-				return state;
-			}
-		}
-		rcu_read_unlock();
-		return AUDIT_BUILD_CONTEXT;
-	}
-
-The read_lock() and read_unlock() calls have become rcu_read_lock()
-and rcu_read_unlock(), respectively, and the list_for_each_entry() has
-become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
-insert the read-side memory barriers that are required on DEC Alpha CPUs.
-
-The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
-
-	static inline int audit_del_rule(struct audit_rule *rule,
-					 struct list_head *list)
-	{
-		struct audit_entry  *e;
-
-		write_lock(&auditsc_lock);
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				list_del(&e->list);
-				write_unlock(&auditsc_lock);
-				return 0;
-			}
-		}
-		write_unlock(&auditsc_lock);
-		return -EFAULT;		/* No matching rule */
-	}
-
-	static inline int audit_add_rule(struct audit_entry *entry,
-					 struct list_head *list)
-	{
-		write_lock(&auditsc_lock);
-		if (entry->rule.flags & AUDIT_PREPEND) {
-			entry->rule.flags &= ~AUDIT_PREPEND;
-			list_add(&entry->list, list);
-		} else {
-			list_add_tail(&entry->list, list);
-		}
-		write_unlock(&auditsc_lock);
-		return 0;
-	}
-
-Following are the RCU equivalents for these two functions:
-
-	static inline int audit_del_rule(struct audit_rule *rule,
-					 struct list_head *list)
-	{
-		struct audit_entry  *e;
-
-		/* Do not use the _rcu iterator here, since this is the only
-		 * deletion routine. */
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				list_del_rcu(&e->list);
-				call_rcu(&e->rcu, audit_free_rule);
-				return 0;
-			}
-		}
-		return -EFAULT;		/* No matching rule */
-	}
-
-	static inline int audit_add_rule(struct audit_entry *entry,
-					 struct list_head *list)
-	{
-		if (entry->rule.flags & AUDIT_PREPEND) {
-			entry->rule.flags &= ~AUDIT_PREPEND;
-			list_add_rcu(&entry->list, list);
-		} else {
-			list_add_tail_rcu(&entry->list, list);
-		}
-		return 0;
-	}
-
-Normally, the write_lock() and write_unlock() would be replaced by
-a spin_lock() and a spin_unlock(), but in this case, all callers hold
-audit_netlink_sem, so no additional locking is required.  The auditsc_lock
-can therefore be eliminated, since use of RCU eliminates the need for
-writers to exclude readers.  Normally, the write_lock() calls would
-be converted into spin_lock() calls.
-
-The list_del(), list_add(), and list_add_tail() primitives have been
-replaced by list_del_rcu(), list_add_rcu(), and list_add_tail_rcu().
-The _rcu() list-manipulation primitives add memory barriers that are
-needed on weakly ordered CPUs (most of them!).  The list_del_rcu()
-primitive omits the pointer poisoning debug-assist code that would
-otherwise cause concurrent readers to fail spectacularly.
-
-So, when readers can tolerate stale data and when entries are either added
-or deleted, without in-place modification, it is very easy to use RCU!
-
-
-Example 2: Handling In-Place Updates
-
-The system-call auditing code does not update auditing rules in place.
-However, if it did, reader-writer-locked code to do so might look as
-follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
-
-	static inline int audit_upd_rule(struct audit_rule *rule,
-					 struct list_head *list,
-					 __u32 newaction,
-					 __u32 newfield_count)
-	{
-		struct audit_entry  *e;
-		struct audit_newentry *ne;
-
-		write_lock(&auditsc_lock);
-		/* Note: audit_netlink_sem held by caller. */
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				e->rule.action = newaction;
-				e->rule.file_count = newfield_count;
-				write_unlock(&auditsc_lock);
-				return 0;
-			}
-		}
-		write_unlock(&auditsc_lock);
-		return -EFAULT;		/* No matching rule */
-	}
-
-The RCU version creates a copy, updates the copy, then replaces the old
-entry with the newly updated entry.  This sequence of actions, allowing
-concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
-
-	static inline int audit_upd_rule(struct audit_rule *rule,
-					 struct list_head *list,
-					 __u32 newaction,
-					 __u32 newfield_count)
-	{
-		struct audit_entry  *e;
-		struct audit_newentry *ne;
-
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
-				if (ne == NULL)
-					return -ENOMEM;
-				audit_copy_rule(&ne->rule, &e->rule);
-				ne->rule.action = newaction;
-				ne->rule.file_count = newfield_count;
-				list_replace_rcu(&e->list, &ne->list);
-				call_rcu(&e->rcu, audit_free_rule);
-				return 0;
-			}
-		}
-		return -EFAULT;		/* No matching rule */
-	}
-
-Again, this assumes that the caller holds audit_netlink_sem.  Normally,
-the reader-writer lock would become a spinlock in this sort of code.
-
-
-Example 3: Eliminating Stale Data
-
-The auditing examples above tolerate stale data, as do most algorithms
-that are tracking external state.  Because there is a delay from the
-time the external state changes before Linux becomes aware of the change,
-additional RCU-induced staleness is normally not a problem.
-
-However, there are many examples where stale data cannot be tolerated.
-One example in the Linux kernel is the System V IPC (see the ipc_lock()
-function in ipc/util.c).  This code checks a "deleted" flag under a
-per-entry spinlock, and, if the "deleted" flag is set, pretends that the
-entry does not exist.  For this to be helpful, the search function must
-return holding the per-entry spinlock, as ipc_lock() does in fact do.
-
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
-
-If the system-call audit module were to ever need to reject stale data,
-one way to accomplish this would be to add a "deleted" flag and a "lock"
-spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
-
-	static enum audit_state audit_filter_task(struct task_struct *tsk)
-	{
-		struct audit_entry *e;
-		enum audit_state   state;
-
-		rcu_read_lock();
-		list_for_each_entry_rcu(e, &audit_tsklist, list) {
-			if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
-				spin_lock(&e->lock);
-				if (e->deleted) {
-					spin_unlock(&e->lock);
-					rcu_read_unlock();
-					return AUDIT_BUILD_CONTEXT;
-				}
-				rcu_read_unlock();
-				return state;
-			}
-		}
-		rcu_read_unlock();
-		return AUDIT_BUILD_CONTEXT;
-	}
-
-Note that this example assumes that entries are only added and deleted.
-Additional mechanism is required to deal correctly with the
-update-in-place performed by audit_upd_rule().  For one thing,
-audit_upd_rule() would need additional memory barriers to ensure
-that the list_add_rcu() was really executed before the list_del_rcu().
-
-The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
-
-	static inline int audit_del_rule(struct audit_rule *rule,
-					 struct list_head *list)
-	{
-		struct audit_entry  *e;
-
-		/* Do not need to use the _rcu iterator here, since this
-		 * is the only deletion routine. */
-		list_for_each_entry(e, list, list) {
-			if (!audit_compare_rule(rule, &e->rule)) {
-				spin_lock(&e->lock);
-				list_del_rcu(&e->list);
-				e->deleted = 1;
-				spin_unlock(&e->lock);
-				call_rcu(&e->rcu, audit_free_rule);
-				return 0;
-			}
-		}
-		return -EFAULT;		/* No matching rule */
-	}
-
-
-Summary
-
-Read-mostly list-based data structures that can tolerate stale data are
-the most amenable to use of RCU.  The simplest case is where entries are
-either added or deleted from the data structure (or atomically modified
-in place), but non-atomic in-place modifications can be handled by making
-a copy, updating the copy, then replacing the original with the copy.
-If stale data cannot be tolerated, then a "deleted" flag may be used
-in conjunction with a per-entry spinlock in order to allow the search
-function to reject newly deleted data.
-
-
-Answer to Quick Quiz
-	Why does the search function need to return holding the per-entry
-	lock for this deleted-flag technique to be helpful?
-
-	If the search function drops the per-entry lock before returning,
-	then the caller will be processing stale data in any case.  If it
-	is really OK to be processing stale data, then you don't need a
-	"deleted" flag.  If processing stale data really is a problem,
-	then you need to hold the per-entry lock across all of the code
-	that uses the value that was returned.
diff --git a/Documentation/RCU/list_rcu.rst b/Documentation/RCU/list_rcu.rst
new file mode 100644
index 000000000000..255c9e173fba
--- /dev/null
+++ b/Documentation/RCU/list_rcu.rst
@@ -0,0 +1,335 @@
+.. _list_rcu_doc:
+
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
+
+One of the best applications of RCU is to protect read-mostly linked lists
+(*struct list_head* in ``list.h``).  One big advantage of this approach
+is that all of the required memory barriers are included for you in
+the list macros.  This document describes several applications of RCU,
+with the best fits first.
+
+Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
+
+The best applications are cases where, if reader-writer locking were
+used, the read-side lock would be dropped before taking any action
+based on the results of the search.  The most celebrated example is
+the routing table.  Because the routing table is tracking the state of
+equipment outside of the computer, it will at times contain stale data.
+Therefore, once the route has been computed, there is no need to hold
+the routing table static during transmission of the packet.  After all,
+you can hold the routing table static all you want, but that won't keep
+the external Internet from changing, and it is the state of the external
+Internet that really matters.  In addition, routing entries are typically
+added or deleted, rather than being modified in place.
+
+A straightforward example of this use of RCU may be found in the
+system-call auditing support.  For example, a reader-writer locked
+implementation of *audit_filter_task()* might be as follows:
+
+.. code-block:: c
+
+   static enum audit_state audit_filter_task(struct task_struct *tsk)
+   {
+      struct audit_entry *e;
+      enum audit_state   state;
+
+      read_lock(&auditsc_lock);
+      /* Note: audit_netlink_sem held by caller. */
+      list_for_each_entry(e, &audit_tsklist, list) {
+         if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+            read_unlock(&auditsc_lock);
+            return state;
+         }
+      }
+      read_unlock(&auditsc_lock);
+      return AUDIT_BUILD_CONTEXT;
+   }
+
+Here the list is searched under the lock, but the lock is dropped before
+the corresponding value is returned.  By the time that this value is acted
+on, the list may well have been modified.  This makes sense, since if
+you are turning auditing off, it is OK to audit a few extra system calls.
+
+This means that RCU can be easily applied to the read side, as follows:
+
+.. code-block:: c
+
+   static enum audit_state audit_filter_task(struct task_struct *tsk)
+   {
+      struct audit_entry *e;
+      enum audit_state   state;
+
+      rcu_read_lock();
+      /* Note: audit_netlink_sem held by caller. */
+      list_for_each_entry_rcu(e, &audit_tsklist, list) {
+         if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+            rcu_read_unlock();
+            return state;
+         }
+      }
+      rcu_read_unlock();
+      return AUDIT_BUILD_CONTEXT;
+   }
+
+The *read_lock()* and *read_unlock()* calls have become *rcu_read_lock()*
+and *rcu_read_unlock()*, respectively, and the *list_for_each_entry()* has
+become *list_for_each_entry_rcu()*.  The *_rcu()* list-traversal primitives
+insert the read-side memory barriers that are required on DEC Alpha CPUs.
+
+The changes to the update side are also straightforward.  A reader-writer
+lock might be used as follows for deletion and insertion:
+
+.. code-block:: c
+
+   static inline int audit_del_rule(struct audit_rule *rule,
+                                    struct list_head *list)
+   {
+      struct audit_entry  *e;
+
+      write_lock(&auditsc_lock);
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            list_del(&e->list);
+            write_unlock(&auditsc_lock);
+            return 0;
+         }
+      }
+      write_unlock(&auditsc_lock);
+      return -EFAULT;   /* No matching rule */
+   }
+
+   static inline int audit_add_rule(struct audit_entry *entry,
+                                    struct list_head *list)
+   {
+      write_lock(&auditsc_lock);
+      if (entry->rule.flags & AUDIT_PREPEND) {
+         entry->rule.flags &= ~AUDIT_PREPEND;
+         list_add(&entry->list, list);
+      } else {
+         list_add_tail(&entry->list, list);
+      }
+      write_unlock(&auditsc_lock);
+      return 0;
+   }
+
+Following are the RCU equivalents for these two functions:
+
+.. code-block:: c
+
+   static inline int audit_del_rule(struct audit_rule *rule,
+                                    struct list_head *list)
+   {
+      struct audit_entry  *e;
+
+      /* Do not use the _rcu iterator here, since this is the only
+       * deletion routine. */
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            list_del_rcu(&e->list);
+            call_rcu(&e->rcu, audit_free_rule);
+            return 0;
+         }
+      }
+      return -EFAULT;   /* No matching rule */
+   }
+
+   static inline int audit_add_rule(struct audit_entry *entry,
+                                    struct list_head *list)
+   {
+      if (entry->rule.flags & AUDIT_PREPEND) {
+         entry->rule.flags &= ~AUDIT_PREPEND;
+         list_add_rcu(&entry->list, list);
+      } else {
+         list_add_tail_rcu(&entry->list, list);
+      }
+      return 0;
+   }
+
+Normally, the *write_lock()* and *write_unlock()* would be replaced by
+a *spin_lock()* and a *spin_unlock()*, but in this case, all callers hold
+*audit_netlink_sem*, so no additional locking is required.  The *auditsc_lock*
+can therefore be eliminated, since use of RCU eliminates the need for
+writers to exclude readers.  Normally, the *write_lock()* calls would
+be converted into *spin_lock()* calls.
+
+The *list_del()*, *list_add()*, and *list_add_tail()* primitives have been
+replaced by *list_del_rcu()*, *list_add_rcu()*, and *list_add_tail_rcu()*.
+The *_rcu()* list-manipulation primitives add memory barriers that are
+needed on weakly ordered CPUs (most of them!).  The *list_del_rcu()*
+primitive omits the pointer poisoning debug-assist code that would
+otherwise cause concurrent readers to fail spectacularly.
+
+So, when readers can tolerate stale data and when entries are either added
+or deleted, without in-place modification, it is very easy to use RCU!
+
+Example 2: Handling In-Place Updates
+------------------------------------
+
+The system-call auditing code does not update auditing rules in place.
+However, if it did, reader-writer-locked code to do so might look as
+follows (presumably, the field_count is only permitted to decrease,
+otherwise, the added fields would need to be filled in):
+
+.. code-block:: c
+
+   static inline int audit_upd_rule(struct audit_rule *rule,
+                                    struct list_head *list,
+                                    __u32 newaction,
+                                    __u32 newfield_count)
+   {
+      struct audit_entry  *e;
+      struct audit_newentry *ne;
+
+      write_lock(&auditsc_lock);
+      /* Note: audit_netlink_sem held by caller. */
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            e->rule.action = newaction;
+            e->rule.file_count = newfield_count;
+            write_unlock(&auditsc_lock);
+            return 0;
+         }
+      }
+      write_unlock(&auditsc_lock);
+      return -EFAULT;   /* No matching rule */
+   }
+
+The RCU version creates a copy, updates the copy, then replaces the old
+entry with the newly updated entry.  This sequence of actions, allowing
+concurrent reads while doing a copy to perform an update, is what gives
+RCU ("read-copy update") its name.  The RCU code is as follows:
+
+.. code-block:: c
+
+   static inline int audit_upd_rule(struct audit_rule *rule,
+                                    struct list_head *list,
+                                    __u32 newaction,
+                                    __u32 newfield_count)
+   {
+      struct audit_entry  *e;
+      struct audit_newentry *ne;
+
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
+            if (ne == NULL)
+               return -ENOMEM;
+            audit_copy_rule(&ne->rule, &e->rule);
+            ne->rule.action = newaction;
+            ne->rule.file_count = newfield_count;
+            list_replace_rcu(&e->list, &ne->list);
+            call_rcu(&e->rcu, audit_free_rule);
+            return 0;
+         }
+      }
+      return -EFAULT;   /* No matching rule */
+   }
+
+Again, this assumes that the caller holds audit_netlink_sem.  Normally,
+the reader-writer lock would become a spinlock in this sort of code.
+
+Example 3: Eliminating Stale Data
+
+The auditing examples above tolerate stale data, as do most algorithms
+that are tracking external state.  Because there is a delay from the
+time the external state changes before Linux becomes aware of the change,
+additional RCU-induced staleness is normally not a problem.
+
+However, there are many examples where stale data cannot be tolerated.
+One example in the Linux kernel is the System V IPC (see the *ipc_lock()*
+function in ``ipc/util.c``).  This code checks a *deleted* flag under a
+per-entry spinlock, and, if the *deleted* flag is set, pretends that the
+entry does not exist.  For this to be helpful, the search function must
+return holding the per-entry spinlock, as *ipc_lock()* does in fact do.
+
+Quick Quiz:  Why does the search function need to return holding the
+	per-entry lock for this deleted-flag technique to be helpful?
+
+:ref:`answer_quick_quiz`
+
+If the system-call audit module were to ever need to reject stale data,
+one way to accomplish this would be to add a *deleted* flag and a *lock*
+spinlock to the *audit_entry* structure, and modify *audit_filter_task()*
+as follows:
+
+.. code-block:: c
+
+   static enum audit_state audit_filter_task(struct task_struct *tsk)
+   {
+      struct audit_entry *e;
+      enum audit_state   state;
+
+      rcu_read_lock();
+      list_for_each_entry_rcu(e, &audit_tsklist, list) {
+         if (audit_filter_rules(tsk, &e->rule, NULL, &state)) {
+            spin_lock(&e->lock);
+            if (e->deleted) {
+               spin_unlock(&e->lock);
+               rcu_read_unlock();
+               return AUDIT_BUILD_CONTEXT;
+            }
+            rcu_read_unlock();
+            return state;
+         }
+      }
+      rcu_read_unlock();
+      return AUDIT_BUILD_CONTEXT;
+   }
+
+Note that this example assumes that entries are only added and deleted.
+Additional mechanism is required to deal correctly with the
+update-in-place performed by *audit_upd_rule()*.  For one thing,
+*audit_upd_rule()* would need additional memory barriers to ensure
+that the *list_add_rcu()* was really executed before the *list_del_rcu()*.
+
+The *audit_del_rule()* function would need to set the *deleted*
+flag under the spinlock as follows:
+
+.. code-block:: c
+
+   static inline int audit_del_rule(struct audit_rule *rule,
+                                    struct list_head *list)
+   {
+      struct audit_entry  *e;
+
+      /* Do not need to use the _rcu iterator here, since this
+       * is the only deletion routine. */
+      list_for_each_entry(e, list, list) {
+         if (!audit_compare_rule(rule, &e->rule)) {
+            spin_lock(&e->lock);
+            list_del_rcu(&e->list);
+            e->deleted = 1;
+            spin_unlock(&e->lock);
+            call_rcu(&e->rcu, audit_free_rule);
+            return 0;
+         }
+      }
+      return -EFAULT;   /* No matching rule */
+   }
+
+.. _answer_quick_quiz:
+
+Summary
+-------
+
+Read-mostly list-based data structures that can tolerate stale data are
+the most amenable to use of RCU.  The simplest case is where entries are
+either added or deleted from the data structure (or atomically modified
+in place), but non-atomic in-place modifications can be handled by making
+a copy, updating the copy, then replacing the original with the copy.
+If stale data cannot be tolerated, then a *deleted* flag may be used
+in conjunction with a per-entry spinlock in order to allow the search
+function to reject newly deleted data.
+
+Answer to Quick Quiz
+	Why does the search function need to return holding the per-entry
+	lock for this deleted-flag technique to be helpful?
+
+	If the search function drops the per-entry lock before returning,
+	then the caller will be processing stale data in any case.  If it
+	is really OK to be processing stale data, then you don't need a
+	"deleted" flag.  If processing stale data really is a problem,
+	then you need to hold the per-entry lock across all of the code
+	that uses the value that was returned.
diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index e95f023d6065..fec4a71e8b95 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -11,7 +11,7 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See listRCU.txt
+a grace period to elapse, then free the element.  See :ref:`list_rcu_doc`
 for more information on using RCU with linked lists.
 
 Frequently Asked Questions
@@ -67,7 +67,7 @@ Frequently Asked Questions
 
 - Why the name "RCU"?
 
-  "RCU" stands for "read-copy update".  listRCU.txt has
+  "RCU" stands for "read-copy update".  :ref:`list_rcu_doc` has
   more information on where this name came from, search for
   "read-copy update" to find it.
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST

[corbet]

On Sat, 22 Jun 2019 02:02:51 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> Convert RCU linked list and add TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/index.rst    |   1 +
>  Documentation/RCU/listRCU.txt  | 315 -------------------------------
>  Documentation/RCU/list_rcu.rst | 335 +++++++++++++++++++++++++++++++++
>  Documentation/RCU/rcu.rst      |   4 +-
>  4 files changed, 338 insertions(+), 317 deletions(-)
>  delete mode 100644 Documentation/RCU/listRCU.txt
>  create mode 100644 Documentation/RCU/list_rcu.rst

Sometimes it can be better to do a change like this in two steps, with the
second being just renaming the file.  That can make it easier to see what
has actually changed.

[...]

> diff --git a/Documentation/RCU/list_rcu.rst b/Documentation/RCU/list_rcu.rst
> new file mode 100644
> index 000000000000..255c9e173fba
> --- /dev/null
> +++ b/Documentation/RCU/list_rcu.rst
> @@ -0,0 +1,335 @@
> +.. _list_rcu_doc:
> +
> +Using RCU to Protect Read-Mostly Linked Lists
> +=============================================
> +
> +One of the best applications of RCU is to protect read-mostly linked lists
> +(*struct list_head* in ``list.h``).  One big advantage of this approach
> +is that all of the required memory barriers are included for you in
> +the list macros.  This document describes several applications of RCU,
> +with the best fits first.
> +
> +Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
> +----------------------------------------------------------------------
> +
> +The best applications are cases where, if reader-writer locking were
> +used, the read-side lock would be dropped before taking any action
> +based on the results of the search.  The most celebrated example is
> +the routing table.  Because the routing table is tracking the state of
> +equipment outside of the computer, it will at times contain stale data.
> +Therefore, once the route has been computed, there is no need to hold
> +the routing table static during transmission of the packet.  After all,
> +you can hold the routing table static all you want, but that won't keep
> +the external Internet from changing, and it is the state of the external
> +Internet that really matters.  In addition, routing entries are typically
> +added or deleted, rather than being modified in place.
> +
> +A straightforward example of this use of RCU may be found in the
> +system-call auditing support.  For example, a reader-writer locked
> +implementation of *audit_filter_task()* might be as follows:

Please don't mark up function names that way.  Just leave them unadorned,
and soon we'll have the magic to handle all of that automatically.  Also,

> +implementation of *audit_filter_task()* might be as follows:
> +
> +.. code-block:: c
> +
> +   static enum audit_state audit_filter_task(struct task_struct *tsk)

It's usually better to just use "::" to indicate a literal block:

> implementation of audit_filter_task() might be as follows::
>
>    static enum audit_state ....

That minimizes the amount of non-text stuff that readers have to work
through.

Thanks,

jon

[Linux-kernel-mentees] [PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST

[Jonathan Corbet]

On Sat, 22 Jun 2019 02:02:51 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> Convert RCU linked list and add TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/index.rst    |   1 +
>  Documentation/RCU/listRCU.txt  | 315 -------------------------------
>  Documentation/RCU/list_rcu.rst | 335 +++++++++++++++++++++++++++++++++
>  Documentation/RCU/rcu.rst      |   4 +-
>  4 files changed, 338 insertions(+), 317 deletions(-)
>  delete mode 100644 Documentation/RCU/listRCU.txt
>  create mode 100644 Documentation/RCU/list_rcu.rst

Sometimes it can be better to do a change like this in two steps, with the
second being just renaming the file.  That can make it easier to see what
has actually changed.

[...]

> diff --git a/Documentation/RCU/list_rcu.rst b/Documentation/RCU/list_rcu.rst
> new file mode 100644
> index 000000000000..255c9e173fba
> --- /dev/null
> +++ b/Documentation/RCU/list_rcu.rst
> @@ -0,0 +1,335 @@
> +.. _list_rcu_doc:
> +
> +Using RCU to Protect Read-Mostly Linked Lists
> +=============================================
> +
> +One of the best applications of RCU is to protect read-mostly linked lists
> +(*struct list_head* in ``list.h``).  One big advantage of this approach
> +is that all of the required memory barriers are included for you in
> +the list macros.  This document describes several applications of RCU,
> +with the best fits first.
> +
> +Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
> +----------------------------------------------------------------------
> +
> +The best applications are cases where, if reader-writer locking were
> +used, the read-side lock would be dropped before taking any action
> +based on the results of the search.  The most celebrated example is
> +the routing table.  Because the routing table is tracking the state of
> +equipment outside of the computer, it will at times contain stale data.
> +Therefore, once the route has been computed, there is no need to hold
> +the routing table static during transmission of the packet.  After all,
> +you can hold the routing table static all you want, but that won't keep
> +the external Internet from changing, and it is the state of the external
> +Internet that really matters.  In addition, routing entries are typically
> +added or deleted, rather than being modified in place.
> +
> +A straightforward example of this use of RCU may be found in the
> +system-call auditing support.  For example, a reader-writer locked
> +implementation of *audit_filter_task()* might be as follows:

Please don't mark up function names that way.  Just leave them unadorned,
and soon we'll have the magic to handle all of that automatically.  Also,

> +implementation of *audit_filter_task()* might be as follows:
> +
> +.. code-block:: c
> +
> +   static enum audit_state audit_filter_task(struct task_struct *tsk)

It's usually better to just use "::" to indicate a literal block:

> implementation of audit_filter_task() might be as follows::
>
>    static enum audit_state ....

That minimizes the amount of non-text stuff that readers have to work
through.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v2 0/7] Documentation: RCU: Convert to

[c0d1n61at3]

This patch series is the initial conversion of the RCU documentation
section.

[PATCH v2 0/7] Documentation: RCU: Convert the following to ReST
[PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
	- ReST markup and TOC tree hook.
[PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
	- Rename RCU basic concepts txt file to rst.
[PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
	- ReST markup and TOC tree hook.
[PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
	- Rename RCU linked list txt file to rst.
[PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
	- ReST markup and TOC tree hook.
[PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
	- Rename RCU UP systems txt file to rst.
[PATCH v2 6/7] Documentation: RCU: Add links to rcu.rst
	- Add the following links to rcu.rst:
		list_rcu
		up_rcu

[PATCH 1/3] Documentation: RCU: Convert RCU basic concepts to ReST
	- Convert RCU basic concepts and add TOC tree hook.
[PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST
	- Convert RCU linked list and add TOC tree hook.
[PATCH 3/3] Documentation: RCU: Convert RCU UP systems to ReST
	- Convert RCU UP systems and add TOC tree hook.

>8-----------------------------------------------------------------8<

Jiunn Chang (7):
  Documentation: RCU: Convert RCU basic concepts to ReST
  Documentation: RCU: Rename RCU basic concepts to ReST
  Documentation: RCU: Convert RCU linked list to ReST
  Documentation: RCU: Rename RCU linked list to ReST
  Documentation: RCU: Convert RCU UP systems to ReST
  Documentation: RCU: Rename RCU UP systems to ReST
  Documentation: RCU: Add links to rcu.rst

 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => list_rcu.rst}         | 33 ++++---
 Documentation/RCU/rcu.rst                     | 91 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 Documentation/RCU/{UP.txt => up_rcu.rst}      | 27 +++---
 5 files changed, 143 insertions(+), 116 deletions(-)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (93%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (89%)

-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 0/7] Documentation: RCU: Convert to

[Jiunn Chang]

This patch series is the initial conversion of the RCU documentation
section.

[PATCH v2 0/7] Documentation: RCU: Convert the following to ReST
[PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
	- ReST markup and TOC tree hook.
[PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
	- Rename RCU basic concepts txt file to rst.
[PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
	- ReST markup and TOC tree hook.
[PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
	- Rename RCU linked list txt file to rst.
[PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
	- ReST markup and TOC tree hook.
[PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
	- Rename RCU UP systems txt file to rst.
[PATCH v2 6/7] Documentation: RCU: Add links to rcu.rst
	- Add the following links to rcu.rst:
		list_rcu
		up_rcu

[PATCH 1/3] Documentation: RCU: Convert RCU basic concepts to ReST
	- Convert RCU basic concepts and add TOC tree hook.
[PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST
	- Convert RCU linked list and add TOC tree hook.
[PATCH 3/3] Documentation: RCU: Convert RCU UP systems to ReST
	- Convert RCU UP systems and add TOC tree hook.

>8-----------------------------------------------------------------8<

Jiunn Chang (7):
  Documentation: RCU: Convert RCU basic concepts to ReST
  Documentation: RCU: Rename RCU basic concepts to ReST
  Documentation: RCU: Convert RCU linked list to ReST
  Documentation: RCU: Rename RCU linked list to ReST
  Documentation: RCU: Convert RCU UP systems to ReST
  Documentation: RCU: Rename RCU UP systems to ReST
  Documentation: RCU: Add links to rcu.rst

 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => list_rcu.rst}         | 33 ++++---
 Documentation/RCU/rcu.rst                     | 91 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 Documentation/RCU/{UP.txt => up_rcu.rst}      | 27 +++---
 5 files changed, 143 insertions(+), 116 deletions(-)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (93%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (89%)

-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 0/7] Documentation: RCU: Convert to

[joel]

Hello Jiunn,

Nice to see the kernel mentees project in action! (I actually did not know
about this project before this posting). I replied to your patches. Once you
address the small nits I suggested, please feel free to add my Reviewed-by
tag to your patches:
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>

If you are interested in RCU, I have some listRCU hardening improvements I am
working on and would be nice to work together with you on that (only if you
are interested).

On Sun, Jun 23, 2019 at 03:14:06AM -0500, Jiunn Chang wrote:
> This patch series is the initial conversion of the RCU documentation
> section.

I think you still did not CC rcu at vger.kernel.org . It would be nice if you
could do that. I think Paul also suggested that in your v1.

thanks!

 - Joel

> 
> [PATCH v2 0/7] Documentation: RCU: Convert the following to ReST
> [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
> 	- Rename RCU basic concepts txt file to rst.
> [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
> 	- Rename RCU linked list txt file to rst.
> [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
> 	- Rename RCU UP systems txt file to rst.
> [PATCH v2 6/7] Documentation: RCU: Add links to rcu.rst
> 	- Add the following links to rcu.rst:
> 		list_rcu
> 		up_rcu
> 
> [PATCH 1/3] Documentation: RCU: Convert RCU basic concepts to ReST
> 	- Convert RCU basic concepts and add TOC tree hook.
> [PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST
> 	- Convert RCU linked list and add TOC tree hook.
> [PATCH 3/3] Documentation: RCU: Convert RCU UP systems to ReST
> 	- Convert RCU UP systems and add TOC tree hook.
> 
> >8-----------------------------------------------------------------8<
> 
> Jiunn Chang (7):
>   Documentation: RCU: Convert RCU basic concepts to ReST
>   Documentation: RCU: Rename RCU basic concepts to ReST
>   Documentation: RCU: Convert RCU linked list to ReST
>   Documentation: RCU: Rename RCU linked list to ReST
>   Documentation: RCU: Convert RCU UP systems to ReST
>   Documentation: RCU: Rename RCU UP systems to ReST
>   Documentation: RCU: Add links to rcu.rst
> 
>  Documentation/RCU/index.rst                   | 19 ++++
>  .../RCU/{listRCU.txt => list_rcu.rst}         | 33 ++++---
>  Documentation/RCU/rcu.rst                     | 91 +++++++++++++++++++
>  Documentation/RCU/rcu.txt                     | 89 ------------------
>  Documentation/RCU/{UP.txt => up_rcu.rst}      | 27 +++---
>  5 files changed, 143 insertions(+), 116 deletions(-)
>  create mode 100644 Documentation/RCU/index.rst
>  rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (93%)
>  create mode 100644 Documentation/RCU/rcu.rst
>  delete mode 100644 Documentation/RCU/rcu.txt
>  rename Documentation/RCU/{UP.txt => up_rcu.rst} (89%)
> 
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v2 0/7] Documentation: RCU: Convert to

[Joel Fernandes]

Hello Jiunn,

Nice to see the kernel mentees project in action! (I actually did not know
about this project before this posting). I replied to your patches. Once you
address the small nits I suggested, please feel free to add my Reviewed-by
tag to your patches:
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>

If you are interested in RCU, I have some listRCU hardening improvements I am
working on and would be nice to work together with you on that (only if you
are interested).

On Sun, Jun 23, 2019 at 03:14:06AM -0500, Jiunn Chang wrote:
> This patch series is the initial conversion of the RCU documentation
> section.

I think you still did not CC rcu at vger.kernel.org . It would be nice if you
could do that. I think Paul also suggested that in your v1.

thanks!

 - Joel

> 
> [PATCH v2 0/7] Documentation: RCU: Convert the following to ReST
> [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
> 	- Rename RCU basic concepts txt file to rst.
> [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
> 	- Rename RCU linked list txt file to rst.
> [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
> 	- Rename RCU UP systems txt file to rst.
> [PATCH v2 6/7] Documentation: RCU: Add links to rcu.rst
> 	- Add the following links to rcu.rst:
> 		list_rcu
> 		up_rcu
> 
> [PATCH 1/3] Documentation: RCU: Convert RCU basic concepts to ReST
> 	- Convert RCU basic concepts and add TOC tree hook.
> [PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST
> 	- Convert RCU linked list and add TOC tree hook.
> [PATCH 3/3] Documentation: RCU: Convert RCU UP systems to ReST
> 	- Convert RCU UP systems and add TOC tree hook.
> 
> >8-----------------------------------------------------------------8<
> 
> Jiunn Chang (7):
>   Documentation: RCU: Convert RCU basic concepts to ReST
>   Documentation: RCU: Rename RCU basic concepts to ReST
>   Documentation: RCU: Convert RCU linked list to ReST
>   Documentation: RCU: Rename RCU linked list to ReST
>   Documentation: RCU: Convert RCU UP systems to ReST
>   Documentation: RCU: Rename RCU UP systems to ReST
>   Documentation: RCU: Add links to rcu.rst
> 
>  Documentation/RCU/index.rst                   | 19 ++++
>  .../RCU/{listRCU.txt => list_rcu.rst}         | 33 ++++---
>  Documentation/RCU/rcu.rst                     | 91 +++++++++++++++++++
>  Documentation/RCU/rcu.txt                     | 89 ------------------
>  Documentation/RCU/{UP.txt => up_rcu.rst}      | 27 +++---
>  5 files changed, 143 insertions(+), 116 deletions(-)
>  create mode 100644 Documentation/RCU/index.rst
>  rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (93%)
>  create mode 100644 Documentation/RCU/rcu.rst
>  delete mode 100644 Documentation/RCU/rcu.txt
>  rename Documentation/RCU/{UP.txt => up_rcu.rst} (89%)
> 
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v2 0/7] Documentation: RCU: Convert to

[corbet]

On Sun, 23 Jun 2019 03:14:06 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> This patch series is the initial conversion of the RCU documentation
> section.
> 
> [PATCH v2 0/7] Documentation: RCU: Convert the following to ReST
> [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
> 	- Rename RCU basic concepts txt file to rst.
> [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
> 	- Rename RCU linked list txt file to rst.
> [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
> 	- Rename RCU UP systems txt file to rst.
> [PATCH v2 6/7] Documentation: RCU: Add links to rcu.rst
> 	- Add the following links to rcu.rst:
> 		list_rcu
> 		up_rcu

Thanks for working on this, we're getting closer.  That said, I have some
overall comments again:

 - Thanks for including a cover letter, but there should be a bit more
   than a list of patches there.  Put in a paragraph saying what the
   series as a whole is for; if somebody reads the cover letter and
   nothing else, they should know what you're up to.

 - The cover letter should also say what has changed since the previous
   posting.

 - Copying the relevant mailing lists really isn't optional, so I'll ask
   you again to do that.  Most maintainers won't accept patches that have
   not been posted to the appropriate public list(s)

 - Please thread your patches as replies to the cover letter, so they all
   stay together.  "git send-email" will do that nicely for you.

 - You have a couple of Reviewed-by tags from Joel now; be sure to add
   those before the next posting.

 - Thanks for splitting out the renames - do you see how that makes it
   easier to see what has actually changed in the files?  That said, you
   could easily and appropriately do all of the renames in a single
   commit.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v2 0/7] Documentation: RCU: Convert to

[Jonathan Corbet]

On Sun, 23 Jun 2019 03:14:06 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> This patch series is the initial conversion of the RCU documentation
> section.
> 
> [PATCH v2 0/7] Documentation: RCU: Convert the following to ReST
> [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
> 	- Rename RCU basic concepts txt file to rst.
> [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
> 	- Rename RCU linked list txt file to rst.
> [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
> 	- ReST markup and TOC tree hook.
> [PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
> 	- Rename RCU UP systems txt file to rst.
> [PATCH v2 6/7] Documentation: RCU: Add links to rcu.rst
> 	- Add the following links to rcu.rst:
> 		list_rcu
> 		up_rcu

Thanks for working on this, we're getting closer.  That said, I have some
overall comments again:

 - Thanks for including a cover letter, but there should be a bit more
   than a list of patches there.  Put in a paragraph saying what the
   series as a whole is for; if somebody reads the cover letter and
   nothing else, they should know what you're up to.

 - The cover letter should also say what has changed since the previous
   posting.

 - Copying the relevant mailing lists really isn't optional, so I'll ask
   you again to do that.  Most maintainers won't accept patches that have
   not been posted to the appropriate public list(s)

 - Please thread your patches as replies to the cover letter, so they all
   stay together.  "git send-email" will do that nicely for you.

 - You have a couple of Reviewed-by tags from Joel now; be sure to add
   those before the next posting.

 - Thanks for splitting out the renames - do you see how that makes it
   easier to see what has actually changed in the files?  That said, you
   could easily and appropriately do all of the renames in a single
   commit.

Thanks,

jon

[Linux-kernel-mentees][PATCH v3 0/6] Documentation: RCU: Convert to reST

[Jiunn Chang]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal and external links have been created with cross-references.
Checkpatch was used to leverage codespell for any spelling errors.  Each patch
in the series has been compiled and reviewed for warnings and errors.
Patches can be bisected.

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8-----------------------------------------------------------------8<

Jiunn Chang (6):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add links to rcu.rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => list_rcu.rst}         | 38 ++++----
 Documentation/RCU/rcu.rst                     | 91 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 Documentation/RCU/{UP.txt => up_rcu.rst}      | 37 +++++---
 5 files changed, 155 insertions(+), 119 deletions(-)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (84%)

-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 0/6] Documentation: RCU: Convert to reST

[Jiunn Chang]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal and external links have been created with cross-references.
Checkpatch was used to leverage codespell for any spelling errors.  Each patch
in the series has been compiled and reviewed for warnings and errors.
Patches can be bisected.

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8-----------------------------------------------------------------8<

Jiunn Chang (6):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add links to rcu.rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => list_rcu.rst}         | 38 ++++----
 Documentation/RCU/rcu.rst                     | 91 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 Documentation/RCU/{UP.txt => up_rcu.rst}      | 37 +++++---
 5 files changed, 155 insertions(+), 119 deletions(-)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (84%)

-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 0/6] Documentation: RCU: Convert to reST

[c0d1n61at3]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal and external links have been created with cross-references.
Checkpatch was used to leverage codespell for any spelling errors.  Each patch
in the series has been compiled and reviewed for warnings and errors.
Patches can be bisected.

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8-----------------------------------------------------------------8<

Jiunn Chang (6):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add links to rcu.rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => list_rcu.rst}         | 38 ++++----
 Documentation/RCU/rcu.rst                     | 91 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 Documentation/RCU/{UP.txt => up_rcu.rst}      | 37 +++++---
 5 files changed, 155 insertions(+), 119 deletions(-)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (84%)

-- 
2.22.0

[Linux-kernel-mentees][PATCH v4 0/5] Documentation: RCU: Convert to reST

[Jiunn Chang]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal links have been created.  Checkpatch was used to leverage codespell
for any spelling errors.  Each patch in the series has been compiled and reviewed
for warnings and errors.  Patches can be bisected.

The changes made in v4 include:
  - Change links in rcu.rst to the path in documentation section
  - Maintain the original name of the txt files

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8---------------------------------------------------------------------------8<

Jiunn Chang (5):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/{UP.txt => UP.rst}          | 37 +++++---
 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => listRCU.rst}          | 38 ++++----
 Documentation/RCU/rcu.rst                     | 92 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 5 files changed, 156 insertions(+), 119 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (84%)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt

-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 0/5] Documentation: RCU: Convert to reST

[Jiunn Chang]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal links have been created.  Checkpatch was used to leverage codespell
for any spelling errors.  Each patch in the series has been compiled and reviewed
for warnings and errors.  Patches can be bisected.

The changes made in v4 include:
  - Change links in rcu.rst to the path in documentation section
  - Maintain the original name of the txt files

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8---------------------------------------------------------------------------8<

Jiunn Chang (5):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/{UP.txt => UP.rst}          | 37 +++++---
 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => listRCU.rst}          | 38 ++++----
 Documentation/RCU/rcu.rst                     | 92 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 5 files changed, 156 insertions(+), 119 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (84%)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt

-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 0/5] Documentation: RCU: Convert to reST

[c0d1n61at3]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal links have been created.  Checkpatch was used to leverage codespell
for any spelling errors.  Each patch in the series has been compiled and reviewed
for warnings and errors.  Patches can be bisected.

The changes made in v4 include:
  - Change links in rcu.rst to the path in documentation section
  - Maintain the original name of the txt files

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8---------------------------------------------------------------------------8<

Jiunn Chang (5):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/{UP.txt => UP.rst}          | 37 +++++---
 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => listRCU.rst}          | 38 ++++----
 Documentation/RCU/rcu.rst                     | 92 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 5 files changed, 156 insertions(+), 119 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (84%)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt

-- 
2.22.0

[Linux-kernel-mentees][PATCH v5 0/5] Documentation: RCU: Convert to reST

[Jiunn Chang]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal links have been created.  Checkpatch was used to leverage codespell
for any spelling errors.  Each patch in the series has been compiled and reviewed
for warnings and errors.  Patches can be bisected.

The changes make in v5 include:
  - add reviewed-by tags

The changes made in v4 include:
  - Change links in rcu.rst to the path in documentation section
  - Maintain the original name of the txt files

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8---------------------------------------------------------------------------8<

Jiunn Chang (5):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/{UP.txt => UP.rst}          | 37 +++++---
 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => listRCU.rst}          | 38 ++++----
 Documentation/RCU/rcu.rst                     | 92 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 5 files changed, 156 insertions(+), 119 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (84%)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt

-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 0/5] Documentation: RCU: Convert to reST

[Jiunn Chang]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal links have been created.  Checkpatch was used to leverage codespell
for any spelling errors.  Each patch in the series has been compiled and reviewed
for warnings and errors.  Patches can be bisected.

The changes make in v5 include:
  - add reviewed-by tags

The changes made in v4 include:
  - Change links in rcu.rst to the path in documentation section
  - Maintain the original name of the txt files

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8---------------------------------------------------------------------------8<

Jiunn Chang (5):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/{UP.txt => UP.rst}          | 37 +++++---
 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => listRCU.rst}          | 38 ++++----
 Documentation/RCU/rcu.rst                     | 92 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 5 files changed, 156 insertions(+), 119 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (84%)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt

-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 0/5] Documentation: RCU: Convert to reST

[c0d1n61at3]

This patch series is the initial conversion of the RCU documentation
section.  This includes reST markup and renaming txt files to rst.  For files
converted, internal links have been created.  Checkpatch was used to leverage codespell
for any spelling errors.  Each patch in the series has been compiled and reviewed
for warnings and errors.  Patches can be bisected.

The changes make in v5 include:
  - add reviewed-by tags

The changes made in v4 include:
  - Change links in rcu.rst to the path in documentation section
  - Maintain the original name of the txt files

The changes made in v3 include:
  - correcting markup to maintain even more of the original text
  - correcting markup for line breaks
  - combining all file renaming into one patch
  - add reviewed-by tags
  - add required public list to CC

The changes made in v2 include:
  - correcting markup to maintain as much of the original text as possible
  - correcting markup to reduce reader context switching
  - breakout file renaming into individual patches in the series

>8---------------------------------------------------------------------------8<

Jiunn Chang (5):
  Documentation: RCU: Convert RCU basic concepts to reST
  Documentation: RCU: Convert RCU linked list to reST
  Documentation: RCU: Convert RCU UP systems to reST
  Documentation: RCU: Rename txt files to rst
  Documentation: RCU: Add TOC tree hooks

 Documentation/RCU/{UP.txt => UP.rst}          | 37 +++++---
 Documentation/RCU/index.rst                   | 19 ++++
 .../RCU/{listRCU.txt => listRCU.rst}          | 38 ++++----
 Documentation/RCU/rcu.rst                     | 92 +++++++++++++++++++
 Documentation/RCU/rcu.txt                     | 89 ------------------
 5 files changed, 156 insertions(+), 119 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (84%)
 create mode 100644 Documentation/RCU/index.rst
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (92%)
 create mode 100644 Documentation/RCU/rcu.rst
 delete mode 100644 Documentation/RCU/rcu.txt

-- 
2.22.0

[Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Jiunn Chang]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
---
 Documentation/RCU/rcu.txt | 119 +++++++++++++++++++-------------------
 1 file changed, 61 insertions(+), 58 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..8dfb437dacc3 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -8,82 +10,83 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
-
+a grace period to elapse, then free the element.  See the
+Documentation/RCU/listRCU.rst file for more information on using RCU with
+linked lists.
 
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the Documentation/RCU/UP.rst file for more information.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file Documentation/RCU/listRCU.rst
+  has more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Jiunn Chang]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
---
 Documentation/RCU/rcu.txt | 119 +++++++++++++++++++-------------------
 1 file changed, 61 insertions(+), 58 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..8dfb437dacc3 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -8,82 +10,83 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
-
+a grace period to elapse, then free the element.  See the
+Documentation/RCU/listRCU.rst file for more information on using RCU with
+linked lists.
 
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the Documentation/RCU/UP.rst file for more information.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file Documentation/RCU/listRCU.rst
+  has more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[c0d1n61at3]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
---
 Documentation/RCU/rcu.txt | 119 +++++++++++++++++++-------------------
 1 file changed, 61 insertions(+), 58 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..8dfb437dacc3 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -8,82 +10,83 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
-
+a grace period to elapse, then free the element.  See the
+Documentation/RCU/listRCU.rst file for more information on using RCU with
+linked lists.
 
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the Documentation/RCU/UP.rst file for more information.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file Documentation/RCU/listRCU.rst
+  has more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

Re: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Jonathan Corbet]

On Wed, 26 Jun 2019 15:07:01 -0500
Jiunn Chang <c0d1n61at3@gmail.com> wrote:

> RCU basic concepts reST markup.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
> Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>

So this is a little detail but ... your signoff should be the last thing
in the set of tags on the patch.

This isn't worth making you do yet another revision, so I went ahead and
applied the patches and fixed the tag ordering on the way in.  I'll also
append a patch adding the new RCU stuff into the core-api manual so people
can actually get to it.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Jonathan Corbet]

On Wed, 26 Jun 2019 15:07:01 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> RCU basic concepts reST markup.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>

So this is a little detail but ... your signoff should be the last thing
in the set of tags on the patch.

This isn't worth making you do yet another revision, so I went ahead and
applied the patches and fixed the tag ordering on the way in.  I'll also
append a patch adding the new RCU stuff into the core-api manual so people
can actually get to it.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[corbet]

On Wed, 26 Jun 2019 15:07:01 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> RCU basic concepts reST markup.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>

So this is a little detail but ... your signoff should be the last thing
in the set of tags on the patch.

This isn't worth making you do yet another revision, so I went ahead and
applied the patches and fixed the tag ordering on the way in.  I'll also
append a patch adding the new RCU stuff into the core-api manual so people
can actually get to it.

Thanks,

jon

Re: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Steven Rostedt]

On Thu, 27 Jun 2019 08:34:43 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3@gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>  
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.

Note, I've been seeing this a lot lately, and then noticed, that when I
downloaded a patch directly from patchwork, it placed all the
Reviewed-by and Acked-by tags after the original Signed-off-by. I
checked the original patch on the mailing list, and it had no other
tags but the Signed-off-by. I then pulled one of my own patches, and it
did it to that patch as well.

I too prefer the Signed-off-by be last, but our tooling needs to do
this as well, otherwise it's a failure in our procedures.

-- Steve

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Steven Rostedt]

On Thu, 27 Jun 2019 08:34:43 -0600
Jonathan Corbet <corbet at lwn.net> wrote:

> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>  
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.

Note, I've been seeing this a lot lately, and then noticed, that when I
downloaded a patch directly from patchwork, it placed all the
Reviewed-by and Acked-by tags after the original Signed-off-by. I
checked the original patch on the mailing list, and it had no other
tags but the Signed-off-by. I then pulled one of my own patches, and it
did it to that patch as well.

I too prefer the Signed-off-by be last, but our tooling needs to do
this as well, otherwise it's a failure in our procedures.

-- Steve

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[rostedt]

On Thu, 27 Jun 2019 08:34:43 -0600
Jonathan Corbet <corbet at lwn.net> wrote:

> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>  
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.

Note, I've been seeing this a lot lately, and then noticed, that when I
downloaded a patch directly from patchwork, it placed all the
Reviewed-by and Acked-by tags after the original Signed-off-by. I
checked the original patch on the mailing list, and it had no other
tags but the Signed-off-by. I then pulled one of my own patches, and it
did it to that patch as well.

I too prefer the Signed-off-by be last, but our tooling needs to do
this as well, otherwise it's a failure in our procedures.

-- Steve

Re: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Shuah Khan]

On 6/27/19 9:13 AM, Steven Rostedt wrote:
> On Thu, 27 Jun 2019 08:34:43 -0600
> Jonathan Corbet <corbet@lwn.net> wrote:
> 
>> On Wed, 26 Jun 2019 15:07:01 -0500
>> Jiunn Chang <c0d1n61at3@gmail.com> wrote:
>>
>>> RCU basic concepts reST markup.
>>>
>>> Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
>>> Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
>>
>> So this is a little detail but ... your signoff should be the last thing
>> in the set of tags on the patch.
> 
> Note, I've been seeing this a lot lately, and then noticed, that when I
> downloaded a patch directly from patchwork, it placed all the
> Reviewed-by and Acked-by tags after the original Signed-off-by. I
> checked the original patch on the mailing list, and it had no other
> tags but the Signed-off-by. I then pulled one of my own patches, and it
> did it to that patch as well.
> 
> I too prefer the Signed-off-by be last, but our tooling needs to do
> this as well, otherwise it's a failure in our procedures.
> 

Thanks Steve for pointing this out. I am seeing some odd behavior with tags.

It appears some maintainers want the tags in chronological order, which
is Reviewed-by after Signed-off which doesn't make sense to me.

I prefer Signed-off-by last.

I am working on FAQ (Frequently Answered Questions) section for mentees.
I will add this to it.

thanks,
-- Shuah

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Shuah Khan]

On 6/27/19 9:13 AM, Steven Rostedt wrote:
> On Thu, 27 Jun 2019 08:34:43 -0600
> Jonathan Corbet <corbet at lwn.net> wrote:
> 
>> On Wed, 26 Jun 2019 15:07:01 -0500
>> Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
>>
>>> RCU basic concepts reST markup.
>>>
>>> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
>>> Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
>>
>> So this is a little detail but ... your signoff should be the last thing
>> in the set of tags on the patch.
> 
> Note, I've been seeing this a lot lately, and then noticed, that when I
> downloaded a patch directly from patchwork, it placed all the
> Reviewed-by and Acked-by tags after the original Signed-off-by. I
> checked the original patch on the mailing list, and it had no other
> tags but the Signed-off-by. I then pulled one of my own patches, and it
> did it to that patch as well.
> 
> I too prefer the Signed-off-by be last, but our tooling needs to do
> this as well, otherwise it's a failure in our procedures.
> 

Thanks Steve for pointing this out. I am seeing some odd behavior with tags.

It appears some maintainers want the tags in chronological order, which
is Reviewed-by after Signed-off which doesn't make sense to me.

I prefer Signed-off-by last.

I am working on FAQ (Frequently Answered Questions) section for mentees.
I will add this to it.

thanks,
-- Shuah

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[skhan]

On 6/27/19 9:13 AM, Steven Rostedt wrote:
> On Thu, 27 Jun 2019 08:34:43 -0600
> Jonathan Corbet <corbet at lwn.net> wrote:
> 
>> On Wed, 26 Jun 2019 15:07:01 -0500
>> Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
>>
>>> RCU basic concepts reST markup.
>>>
>>> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
>>> Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
>>
>> So this is a little detail but ... your signoff should be the last thing
>> in the set of tags on the patch.
> 
> Note, I've been seeing this a lot lately, and then noticed, that when I
> downloaded a patch directly from patchwork, it placed all the
> Reviewed-by and Acked-by tags after the original Signed-off-by. I
> checked the original patch on the mailing list, and it had no other
> tags but the Signed-off-by. I then pulled one of my own patches, and it
> did it to that patch as well.
> 
> I too prefer the Signed-off-by be last, but our tooling needs to do
> this as well, otherwise it's a failure in our procedures.
> 

Thanks Steve for pointing this out. I am seeing some odd behavior with tags.

It appears some maintainers want the tags in chronological order, which
is Reviewed-by after Signed-off which doesn't make sense to me.

I prefer Signed-off-by last.

I am working on FAQ (Frequently Answered Questions) section for mentees.
I will add this to it.

thanks,
-- Shuah

Re: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Paul E. McKenney]

On Thu, Jun 27, 2019 at 08:34:43AM -0600, Jonathan Corbet wrote:
> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3@gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.
> 
> This isn't worth making you do yet another revision, so I went ahead and
> applied the patches and fixed the tag ordering on the way in.  I'll also
> append a patch adding the new RCU stuff into the core-api manual so people
> can actually get to it.

Please feel free to add my ack:

Acked-by: Paul E. McKenney <paulmck@linux.ibm.com>

							Thanx, Paul

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Paul E. McKenney]

On Thu, Jun 27, 2019 at 08:34:43AM -0600, Jonathan Corbet wrote:
> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.
> 
> This isn't worth making you do yet another revision, so I went ahead and
> applied the patches and fixed the tag ordering on the way in.  I'll also
> append a patch adding the new RCU stuff into the core-api manual so people
> can actually get to it.

Please feel free to add my ack:

Acked-by: Paul E. McKenney <paulmck at linux.ibm.com>

							Thanx, Paul

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[paulmck]

On Thu, Jun 27, 2019 at 08:34:43AM -0600, Jonathan Corbet wrote:
> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.
> 
> This isn't worth making you do yet another revision, so I went ahead and
> applied the patches and fixed the tag ordering on the way in.  I'll also
> append a patch adding the new RCU stuff into the core-api manual so people
> can actually get to it.

Please feel free to add my ack:

Acked-by: Paul E. McKenney <paulmck at linux.ibm.com>

							Thanx, Paul

Re: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Jiunn Chang]

On Thu, Jun 27, 2019 at 08:34:43AM -0600, Jonathan Corbet wrote:
> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3@gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.
> 
> This isn't worth making you do yet another revision, so I went ahead and
> applied the patches and fixed the tag ordering on the way in.  I'll also
> append a patch adding the new RCU stuff into the core-api manual so people
> can actually get to it.
> 
> Thanks,
> 
> jon

Hello Jon,

I will keep this in mind for next time.  I would like to thank you, Joel, Paul
and everyone else who has helped me learn the Linux kernel patch process.

I will send a patch for the UP systems change Paul sent me for _bh suffix.

THX,

Jiunn

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Jiunn Chang]

On Thu, Jun 27, 2019 at 08:34:43AM -0600, Jonathan Corbet wrote:
> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.
> 
> This isn't worth making you do yet another revision, so I went ahead and
> applied the patches and fixed the tag ordering on the way in.  I'll also
> append a patch adding the new RCU stuff into the core-api manual so people
> can actually get to it.
> 
> Thanks,
> 
> jon

Hello Jon,

I will keep this in mind for next time.  I would like to thank you, Joel, Paul
and everyone else who has helped me learn the Linux kernel patch process.

I will send a patch for the UP systems change Paul sent me for _bh suffix.

THX,

Jiunn

[Linux-kernel-mentees] [PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[c0d1n61at3]

On Thu, Jun 27, 2019 at 08:34:43AM -0600, Jonathan Corbet wrote:
> On Wed, 26 Jun 2019 15:07:01 -0500
> Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
> 
> > RCU basic concepts reST markup.
> > 
> > Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> > Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
> 
> So this is a little detail but ... your signoff should be the last thing
> in the set of tags on the patch.
> 
> This isn't worth making you do yet another revision, so I went ahead and
> applied the patches and fixed the tag ordering on the way in.  I'll also
> append a patch adding the new RCU stuff into the core-api manual so people
> can actually get to it.
> 
> Thanks,
> 
> jon

Hello Jon,

I will keep this in mind for next time.  I would like to thank you, Joel, Paul
and everyone else who has helped me learn the Linux kernel patch process.

I will send a patch for the UP systems change Paul sent me for _bh suffix.

THX,

Jiunn

[Linux-kernel-mentees][PATCH v5 2/5] Documentation: RCU: Convert RCU linked list to reST

[Jiunn Chang]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 2/5] Documentation: RCU: Convert RCU linked list to reST

[Jiunn Chang]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 2/5] Documentation: RCU: Convert RCU linked list to reST

[c0d1n61at3]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees][PATCH v5 3/5] Documentation: RCU: Convert RCU UP systems to reST

[Jiunn Chang]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 3/5] Documentation: RCU: Convert RCU UP systems to reST

[Jiunn Chang]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 3/5] Documentation: RCU: Convert RCU UP systems to reST

[c0d1n61at3]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

[Linux-kernel-mentees][PATCH v5 4/5] Documentation: RCU: Rename txt files to rst

[Jiunn Chang]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/{UP.txt => UP.rst}           | 0
 Documentation/RCU/{listRCU.txt => listRCU.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}         | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (100%)
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/UP.rst
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/listRCU.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 4/5] Documentation: RCU: Rename txt files to rst

[Jiunn Chang]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{UP.txt => UP.rst}           | 0
 Documentation/RCU/{listRCU.txt => listRCU.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}         | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (100%)
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/UP.rst
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/listRCU.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 4/5] Documentation: RCU: Rename txt files to rst

[c0d1n61at3]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{UP.txt => UP.rst}           | 0
 Documentation/RCU/{listRCU.txt => listRCU.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}         | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (100%)
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/UP.rst
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/listRCU.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
-- 
2.22.0

[Linux-kernel-mentees][PATCH v5 5/5] Documentation: RCU: Add TOC tree hooks

[Jiunn Chang]

Add TOC tree hooks for:
  - rcu
  - listRCU
  - UP

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..340a9725676c
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   listRCU
+   UP
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 5/5] Documentation: RCU: Add TOC tree hooks

[Jiunn Chang]

Add TOC tree hooks for:
  - rcu
  - listRCU
  - UP

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..340a9725676c
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   listRCU
+   UP
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v5 5/5] Documentation: RCU: Add TOC tree hooks

[c0d1n61at3]

Add TOC tree hooks for:
  - rcu
  - listRCU
  - UP

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..340a9725676c
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   listRCU
+   UP
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees][PATCH v4 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Jiunn Chang]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/rcu.txt | 119 +++++++++++++++++++-------------------
 1 file changed, 61 insertions(+), 58 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..8dfb437dacc3 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -8,82 +10,83 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
-
+a grace period to elapse, then free the element.  See the
+Documentation/RCU/listRCU.rst file for more information on using RCU with
+linked lists.
 
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the Documentation/RCU/UP.rst file for more information.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file Documentation/RCU/listRCU.rst
+  has more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[Jiunn Chang]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/rcu.txt | 119 +++++++++++++++++++-------------------
 1 file changed, 61 insertions(+), 58 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..8dfb437dacc3 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -8,82 +10,83 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
-
+a grace period to elapse, then free the element.  See the
+Documentation/RCU/listRCU.rst file for more information on using RCU with
+linked lists.
 
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the Documentation/RCU/UP.rst file for more information.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file Documentation/RCU/listRCU.rst
+  has more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 1/5] Documentation: RCU: Convert RCU basic concepts to reST

[c0d1n61at3]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/rcu.txt | 119 +++++++++++++++++++-------------------
 1 file changed, 61 insertions(+), 58 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..8dfb437dacc3 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -8,82 +10,83 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
-
+a grace period to elapse, then free the element.  See the
+Documentation/RCU/listRCU.rst file for more information on using RCU with
+linked lists.
 
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the Documentation/RCU/UP.rst file for more information.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file Documentation/RCU/listRCU.rst
+  has more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees][PATCH v4 2/5] Documentation: RCU: Convert RCU linked list to reST

[Jiunn Chang]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 2/5] Documentation: RCU: Convert RCU linked list to reST

[Jiunn Chang]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 2/5] Documentation: RCU: Convert RCU linked list to reST

[c0d1n61at3]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees][PATCH v4 3/5] Documentation: RCU: Convert RCU UP systems to reST

[Jiunn Chang]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 3/5] Documentation: RCU: Convert RCU UP systems to reST

[Jiunn Chang]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 3/5] Documentation: RCU: Convert RCU UP systems to reST

[c0d1n61at3]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

[Linux-kernel-mentees][PATCH v4 4/5] Documentation: RCU: Rename txt files to rst

[Jiunn Chang]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/{UP.txt => UP.rst}           | 0
 Documentation/RCU/{listRCU.txt => listRCU.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}         | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (100%)
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/UP.rst
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/listRCU.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 4/5] Documentation: RCU: Rename txt files to rst

[Jiunn Chang]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{UP.txt => UP.rst}           | 0
 Documentation/RCU/{listRCU.txt => listRCU.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}         | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (100%)
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/UP.rst
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/listRCU.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 4/5] Documentation: RCU: Rename txt files to rst

[c0d1n61at3]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{UP.txt => UP.rst}           | 0
 Documentation/RCU/{listRCU.txt => listRCU.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}         | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{UP.txt => UP.rst} (100%)
 rename Documentation/RCU/{listRCU.txt => listRCU.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/UP.rst
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/listRCU.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
-- 
2.22.0

[Linux-kernel-mentees][PATCH v4 5/5] Documentation: RCU: Add TOC tree hooks

[Jiunn Chang]

Add TOC tree hooks for:
  - rcu
  - listRCU
  - UP

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..340a9725676c
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   listRCU
+   UP
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 5/5] Documentation: RCU: Add TOC tree hooks

[Jiunn Chang]

Add TOC tree hooks for:
  - rcu
  - listRCU
  - UP

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..340a9725676c
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   listRCU
+   UP
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v4 5/5] Documentation: RCU: Add TOC tree hooks

[c0d1n61at3]

Add TOC tree hooks for:
  - rcu
  - listRCU
  - UP

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..340a9725676c
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   listRCU
+   UP
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees][PATCH v3 1/6] Documentation: RCU: Convert RCU basic concepts to reST

[Jiunn Chang]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
---
 Documentation/RCU/rcu.txt | 114 +++++++++++++++++++-------------------
 1 file changed, 58 insertions(+), 56 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..000da07d683e 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -11,79 +13,79 @@ from a linked list would first remove the item from the list, wait for
 a grace period to elapse, then free the element.  See the listRCU.txt
 file for more information on using RCU with linked lists.
 
-
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the UP.txt file in this directory.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 1/6] Documentation: RCU: Convert RCU basic concepts to reST

[Jiunn Chang]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
---
 Documentation/RCU/rcu.txt | 114 +++++++++++++++++++-------------------
 1 file changed, 58 insertions(+), 56 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..000da07d683e 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -11,79 +13,79 @@ from a linked list would first remove the item from the list, wait for
 a grace period to elapse, then free the element.  See the listRCU.txt
 file for more information on using RCU with linked lists.
 
-
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the UP.txt file in this directory.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 1/6] Documentation: RCU: Convert RCU basic concepts to reST

[c0d1n61at3]

RCU basic concepts reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
---
 Documentation/RCU/rcu.txt | 114 +++++++++++++++++++-------------------
 1 file changed, 58 insertions(+), 56 deletions(-)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..000da07d683e 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,7 @@
-RCU Concepts
+.. _rcu_doc:
 
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -11,79 +13,79 @@ from a linked list would first remove the item from the list, wait for
 a grace period to elapse, then free the element.  See the listRCU.txt
 file for more information on using RCU with linked lists.
 
-
 Frequently Asked Questions
+--------------------------
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the UP.txt file in this directory.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees][PATCH v3 2/6] Documentation: RCU: Convert RCU linked list to reST

[Jiunn Chang]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 2/6] Documentation: RCU: Convert RCU linked list to reST

[Jiunn Chang]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 2/6] Documentation: RCU: Convert RCU linked list to reST

[c0d1n61at3]

RCU linked list reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++---------------
 1 file changed, 22 insertions(+), 16 deletions(-)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..7956ff33042b 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,5 +1,7 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
 ("struct list_head" in list.h).  One big advantage of this approach
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
 entry does not exist.  For this to be helpful, the search function must
 return holding the per-entry spinlock, as ipc_lock() does in fact do.
 
-Quick Quiz:  Why does the search function need to return holding the
-	per-entry lock for this deleted-flag technique to be helpful?
+Quick Quiz:
+	Why does the search function need to return holding the per-entry lock for
+	this deleted-flag technique to be helpful?
+
+:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
 
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
-
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
+.. _answer_quick_quiz_list:
 
-Answer to Quick Quiz
+Answer to Quick Quiz:
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
 
-- 
2.22.0

[Linux-kernel-mentees][PATCH v3 3/6] Documentation: RCU: Convert RCU UP systems to reST

[Jiunn Chang]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 3/6] Documentation: RCU: Convert RCU UP systems to reST

[Jiunn Chang]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 3/6] Documentation: RCU: Convert RCU UP systems to reST

[c0d1n61at3]

RCU UP systems reST markup.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
---
 Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..67715a47ae89 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
-	this case?
+Quick Quiz #1:
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
 If call_rcu() directly invokes the callback, painful locking restrictions
 or API changes would be required.
 
-Quick Quiz #2: What locking restriction must RCU callbacks respect?
+Quick Quiz #2:
+	What locking restriction must RCU callbacks respect?
 
+:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
 
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
-Quick Quiz #3: Why can't synchronize_rcu() return immediately on
-	UP systems running preemptable RCU?
+Quick Quiz #3:
+	Why can't synchronize_rcu() return immediately on UP systems running
+	preemptable RCU?
 
+.. _answer_quick_quiz_up:
 
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
-- 
2.22.0

Re: [Linux-kernel-mentees][PATCH v3 3/6] Documentation: RCU: Convert RCU UP systems to reST

[Paul E. McKenney]

On Tue, Jun 25, 2019 at 01:26:24AM -0500, Jiunn Chang wrote:
> RCU UP systems reST markup.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
> Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
> ---
>  Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
>  1 file changed, 23 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..67715a47ae89 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:
>  
> +RCU on Uniprocessor Systems
> +===========================
>  
>  A common misconception is that, on UP systems, the call_rcu() primitive
>  may immediately invoke its function.  The basis of this misconception
>  is that since there is only one CPU, it should not be necessary to
>  wait for anything else to get done, since there are no other CPUs for
> -anything else to be happening on.  Although this approach will -sort- -of-
> +anything else to be happening on.  Although this approach will *sort of*
>  work a surprising amount of the time, it is a very bad idea in general.
>  This document presents three examples that demonstrate exactly how bad
>  an idea this is.
>  
> -
>  Example 1: softirq Suicide
> +--------------------------
>  
>  Suppose that an RCU-based algorithm scans a linked list containing
>  elements A, B, and C in process context, and can delete elements from
> @@ -28,8 +30,8 @@ your kernel.
>  This same problem can occur if call_rcu() is invoked from a hardware
>  interrupt handler.
>  
> -
>  Example 2: Function-Call Fatality
> +---------------------------------
>  
>  Of course, one could avert the suicide described in the preceding example
>  by having call_rcu() directly invoke its arguments only if it was called
> @@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
>  underlying RCU, namely that call_rcu() defers invoking its arguments until
>  all RCU read-side critical sections currently executing have completed.
>  
> -Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
> -	this case?
> +Quick Quiz #1:
> +	Why is it *not* legal to invoke synchronize_rcu() in this case?
>  
> +:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
>  
>  Example 3: Death by Deadlock
> +----------------------------
>  
>  Suppose that call_rcu() is invoked while holding a lock, and that the
>  callback function must acquire this same lock.  In this case, if
> @@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
>  If call_rcu() directly invokes the callback, painful locking restrictions
>  or API changes would be required.
>  
> -Quick Quiz #2: What locking restriction must RCU callbacks respect?
> +Quick Quiz #2:
> +	What locking restriction must RCU callbacks respect?
>  
> +:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
>  
>  Summary
> +-------
>  
>  Permitting call_rcu() to immediately invoke its arguments breaks RCU,
>  even on a UP system.  So do not do it!  Even on a UP system, the RCU
> -infrastructure -must- respect grace periods, and -must- invoke callbacks
> +infrastructure *must* respect grace periods, and *must* invoke callbacks
>  from a known environment in which no locks are held.
>  
> -Note that it -is- safe for synchronize_rcu() to return immediately on
> -UP systems, including !PREEMPT SMP builds running on UP systems.
> +Note that it *is* safe for synchronize_rcu() to return immediately on
> +UP systems, including PREEMPT SMP builds running on UP systems.
>  
> -Quick Quiz #3: Why can't synchronize_rcu() return immediately on
> -	UP systems running preemptable RCU?
> +Quick Quiz #3:
> +	Why can't synchronize_rcu() return immediately on UP systems running
> +	preemptable RCU?
>  
> +.. _answer_quick_quiz_up:

As long as you are in the area, the answer is overly constraining.
The locking primitives could use either _irq suffixes (as stated) or
_bh suffixes.  This is obviously not your fault, but please feel free
to fix this with an additional patch.

							Thanx, Paul

>  Answer to Quick Quiz #1:
> -	Why is it -not- legal to invoke synchronize_rcu() in this case?
> +	Why is it *not* legal to invoke synchronize_rcu() in this case?
>  
>  	Because the calling function is scanning an RCU-protected linked
>  	list, and is therefore within an RCU read-side critical section.
> @@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
>  
>  	This restriction might seem gratuitous, since very few RCU
>  	callbacks acquire locks directly.  However, a great many RCU
> -	callbacks do acquire locks -indirectly-, for example, via
> +	callbacks do acquire locks *indirectly*, for example, via
>  	the kfree() primitive.
>  
>  Answer to Quick Quiz #3:
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v3 3/6] Documentation: RCU: Convert RCU UP systems to reST

[Paul E. McKenney]

On Tue, Jun 25, 2019 at 01:26:24AM -0500, Jiunn Chang wrote:
> RCU UP systems reST markup.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
> ---
>  Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
>  1 file changed, 23 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..67715a47ae89 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:
>  
> +RCU on Uniprocessor Systems
> +===========================
>  
>  A common misconception is that, on UP systems, the call_rcu() primitive
>  may immediately invoke its function.  The basis of this misconception
>  is that since there is only one CPU, it should not be necessary to
>  wait for anything else to get done, since there are no other CPUs for
> -anything else to be happening on.  Although this approach will -sort- -of-
> +anything else to be happening on.  Although this approach will *sort of*
>  work a surprising amount of the time, it is a very bad idea in general.
>  This document presents three examples that demonstrate exactly how bad
>  an idea this is.
>  
> -
>  Example 1: softirq Suicide
> +--------------------------
>  
>  Suppose that an RCU-based algorithm scans a linked list containing
>  elements A, B, and C in process context, and can delete elements from
> @@ -28,8 +30,8 @@ your kernel.
>  This same problem can occur if call_rcu() is invoked from a hardware
>  interrupt handler.
>  
> -
>  Example 2: Function-Call Fatality
> +---------------------------------
>  
>  Of course, one could avert the suicide described in the preceding example
>  by having call_rcu() directly invoke its arguments only if it was called
> @@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
>  underlying RCU, namely that call_rcu() defers invoking its arguments until
>  all RCU read-side critical sections currently executing have completed.
>  
> -Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
> -	this case?
> +Quick Quiz #1:
> +	Why is it *not* legal to invoke synchronize_rcu() in this case?
>  
> +:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
>  
>  Example 3: Death by Deadlock
> +----------------------------
>  
>  Suppose that call_rcu() is invoked while holding a lock, and that the
>  callback function must acquire this same lock.  In this case, if
> @@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
>  If call_rcu() directly invokes the callback, painful locking restrictions
>  or API changes would be required.
>  
> -Quick Quiz #2: What locking restriction must RCU callbacks respect?
> +Quick Quiz #2:
> +	What locking restriction must RCU callbacks respect?
>  
> +:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
>  
>  Summary
> +-------
>  
>  Permitting call_rcu() to immediately invoke its arguments breaks RCU,
>  even on a UP system.  So do not do it!  Even on a UP system, the RCU
> -infrastructure -must- respect grace periods, and -must- invoke callbacks
> +infrastructure *must* respect grace periods, and *must* invoke callbacks
>  from a known environment in which no locks are held.
>  
> -Note that it -is- safe for synchronize_rcu() to return immediately on
> -UP systems, including !PREEMPT SMP builds running on UP systems.
> +Note that it *is* safe for synchronize_rcu() to return immediately on
> +UP systems, including PREEMPT SMP builds running on UP systems.
>  
> -Quick Quiz #3: Why can't synchronize_rcu() return immediately on
> -	UP systems running preemptable RCU?
> +Quick Quiz #3:
> +	Why can't synchronize_rcu() return immediately on UP systems running
> +	preemptable RCU?
>  
> +.. _answer_quick_quiz_up:

As long as you are in the area, the answer is overly constraining.
The locking primitives could use either _irq suffixes (as stated) or
_bh suffixes.  This is obviously not your fault, but please feel free
to fix this with an additional patch.

							Thanx, Paul

>  Answer to Quick Quiz #1:
> -	Why is it -not- legal to invoke synchronize_rcu() in this case?
> +	Why is it *not* legal to invoke synchronize_rcu() in this case?
>  
>  	Because the calling function is scanning an RCU-protected linked
>  	list, and is therefore within an RCU read-side critical section.
> @@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
>  
>  	This restriction might seem gratuitous, since very few RCU
>  	callbacks acquire locks directly.  However, a great many RCU
> -	callbacks do acquire locks -indirectly-, for example, via
> +	callbacks do acquire locks *indirectly*, for example, via
>  	the kfree() primitive.
>  
>  Answer to Quick Quiz #3:
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v3 3/6] Documentation: RCU: Convert RCU UP systems to reST

[paulmck]

On Tue, Jun 25, 2019 at 01:26:24AM -0500, Jiunn Chang wrote:
> RCU UP systems reST markup.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
> ---
>  Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++--------------
>  1 file changed, 23 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..67715a47ae89 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:
>  
> +RCU on Uniprocessor Systems
> +===========================
>  
>  A common misconception is that, on UP systems, the call_rcu() primitive
>  may immediately invoke its function.  The basis of this misconception
>  is that since there is only one CPU, it should not be necessary to
>  wait for anything else to get done, since there are no other CPUs for
> -anything else to be happening on.  Although this approach will -sort- -of-
> +anything else to be happening on.  Although this approach will *sort of*
>  work a surprising amount of the time, it is a very bad idea in general.
>  This document presents three examples that demonstrate exactly how bad
>  an idea this is.
>  
> -
>  Example 1: softirq Suicide
> +--------------------------
>  
>  Suppose that an RCU-based algorithm scans a linked list containing
>  elements A, B, and C in process context, and can delete elements from
> @@ -28,8 +30,8 @@ your kernel.
>  This same problem can occur if call_rcu() is invoked from a hardware
>  interrupt handler.
>  
> -
>  Example 2: Function-Call Fatality
> +---------------------------------
>  
>  Of course, one could avert the suicide described in the preceding example
>  by having call_rcu() directly invoke its arguments only if it was called
> @@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
>  underlying RCU, namely that call_rcu() defers invoking its arguments until
>  all RCU read-side critical sections currently executing have completed.
>  
> -Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
> -	this case?
> +Quick Quiz #1:
> +	Why is it *not* legal to invoke synchronize_rcu() in this case?
>  
> +:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
>  
>  Example 3: Death by Deadlock
> +----------------------------
>  
>  Suppose that call_rcu() is invoked while holding a lock, and that the
>  callback function must acquire this same lock.  In this case, if
> @@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
>  If call_rcu() directly invokes the callback, painful locking restrictions
>  or API changes would be required.
>  
> -Quick Quiz #2: What locking restriction must RCU callbacks respect?
> +Quick Quiz #2:
> +	What locking restriction must RCU callbacks respect?
>  
> +:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
>  
>  Summary
> +-------
>  
>  Permitting call_rcu() to immediately invoke its arguments breaks RCU,
>  even on a UP system.  So do not do it!  Even on a UP system, the RCU
> -infrastructure -must- respect grace periods, and -must- invoke callbacks
> +infrastructure *must* respect grace periods, and *must* invoke callbacks
>  from a known environment in which no locks are held.
>  
> -Note that it -is- safe for synchronize_rcu() to return immediately on
> -UP systems, including !PREEMPT SMP builds running on UP systems.
> +Note that it *is* safe for synchronize_rcu() to return immediately on
> +UP systems, including PREEMPT SMP builds running on UP systems.
>  
> -Quick Quiz #3: Why can't synchronize_rcu() return immediately on
> -	UP systems running preemptable RCU?
> +Quick Quiz #3:
> +	Why can't synchronize_rcu() return immediately on UP systems running
> +	preemptable RCU?
>  
> +.. _answer_quick_quiz_up:

As long as you are in the area, the answer is overly constraining.
The locking primitives could use either _irq suffixes (as stated) or
_bh suffixes.  This is obviously not your fault, but please feel free
to fix this with an additional patch.

							Thanx, Paul

>  Answer to Quick Quiz #1:
> -	Why is it -not- legal to invoke synchronize_rcu() in this case?
> +	Why is it *not* legal to invoke synchronize_rcu() in this case?
>  
>  	Because the calling function is scanning an RCU-protected linked
>  	list, and is therefore within an RCU read-side critical section.
> @@ -119,7 +128,7 @@ Answer to Quick Quiz #2:
>  
>  	This restriction might seem gratuitous, since very few RCU
>  	callbacks acquire locks directly.  However, a great many RCU
> -	callbacks do acquire locks -indirectly-, for example, via
> +	callbacks do acquire locks *indirectly*, for example, via
>  	the kfree() primitive.
>  
>  Answer to Quick Quiz #3:
> -- 
> 2.22.0
> 

[Linux-kernel-mentees][PATCH v3 4/6] Documentation: RCU: Rename txt files to rst

[Jiunn Chang]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/{listRCU.txt => list_rcu.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}          | 0
 Documentation/RCU/{UP.txt => up_rcu.rst}        | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (100%)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/list_rcu.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/list_rcu.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/up_rcu.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/up_rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 4/6] Documentation: RCU: Rename txt files to rst

[Jiunn Chang]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{listRCU.txt => list_rcu.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}          | 0
 Documentation/RCU/{UP.txt => up_rcu.rst}        | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (100%)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/list_rcu.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/list_rcu.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/up_rcu.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/up_rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 4/6] Documentation: RCU: Rename txt files to rst

[c0d1n61at3]

Rename the following files to reST:
  - rcu.txt
  - listRCU.txt
  - UP.txt

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{listRCU.txt => list_rcu.rst} | 0
 Documentation/RCU/{rcu.txt => rcu.rst}          | 0
 Documentation/RCU/{UP.txt => up_rcu.rst}        | 0
 3 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (100%)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (100%)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/list_rcu.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/list_rcu.rst
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/up_rcu.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/up_rcu.rst
-- 
2.22.0

[Linux-kernel-mentees][PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Jiunn Chang]

Add the following links:
  - list_rcu
  - up_rcu

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/rcu.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 000da07d683e..d145decb5c39 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -10,8 +10,8 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
+a grace period to elapse, then free the element.  See :ref:`list_rcu`
+for more information on using RCU with linked lists.
 
 Frequently Asked Questions
 --------------------------
@@ -49,7 +49,7 @@ Frequently Asked Questions
 - If I am running on a uniprocessor kernel, which can only do one
   thing at a time, why should I wait for a grace period?
 
-  See the UP.txt file in this directory.
+  See :ref:`up_rcu` for more information.
 
 - How can I see where RCU is currently used in the Linux kernel?
 
@@ -67,7 +67,7 @@ Frequently Asked Questions
 
 - Why the name "RCU"?
 
-  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  "RCU" stands for "read-copy update".  :ref:`list_rcu` has
   more information on where this name came from, search for
   "read-copy update" to find it.
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Jiunn Chang]

Add the following links:
  - list_rcu
  - up_rcu

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/rcu.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 000da07d683e..d145decb5c39 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -10,8 +10,8 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
+a grace period to elapse, then free the element.  See :ref:`list_rcu`
+for more information on using RCU with linked lists.
 
 Frequently Asked Questions
 --------------------------
@@ -49,7 +49,7 @@ Frequently Asked Questions
 - If I am running on a uniprocessor kernel, which can only do one
   thing at a time, why should I wait for a grace period?
 
-  See the UP.txt file in this directory.
+  See :ref:`up_rcu` for more information.
 
 - How can I see where RCU is currently used in the Linux kernel?
 
@@ -67,7 +67,7 @@ Frequently Asked Questions
 
 - Why the name "RCU"?
 
-  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  "RCU" stands for "read-copy update".  :ref:`list_rcu` has
   more information on where this name came from, search for
   "read-copy update" to find it.
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[c0d1n61at3]

Add the following links:
  - list_rcu
  - up_rcu

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/rcu.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 000da07d683e..d145decb5c39 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -10,8 +10,8 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
+a grace period to elapse, then free the element.  See :ref:`list_rcu`
+for more information on using RCU with linked lists.
 
 Frequently Asked Questions
 --------------------------
@@ -49,7 +49,7 @@ Frequently Asked Questions
 - If I am running on a uniprocessor kernel, which can only do one
   thing at a time, why should I wait for a grace period?
 
-  See the UP.txt file in this directory.
+  See :ref:`up_rcu` for more information.
 
 - How can I see where RCU is currently used in the Linux kernel?
 
@@ -67,7 +67,7 @@ Frequently Asked Questions
 
 - Why the name "RCU"?
 
-  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  "RCU" stands for "read-copy update".  :ref:`list_rcu` has
   more information on where this name came from, search for
   "read-copy update" to find it.
 
-- 
2.22.0

Re: [Linux-kernel-mentees][PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Paul E. McKenney]

On Tue, Jun 25, 2019 at 01:26:26AM -0500, Jiunn Chang wrote:
> Add the following links:
>   - list_rcu
>   - up_rcu
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
> ---
>  Documentation/RCU/rcu.rst | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
> index 000da07d683e..d145decb5c39 100644
> --- a/Documentation/RCU/rcu.rst
> +++ b/Documentation/RCU/rcu.rst
> @@ -10,8 +10,8 @@ A "grace period" must elapse between the two parts, and this grace period
>  must be long enough that any readers accessing the item being deleted have
>  since dropped their references.  For example, an RCU-protected deletion
>  from a linked list would first remove the item from the list, wait for
> -a grace period to elapse, then free the element.  See the listRCU.txt
> -file for more information on using RCU with linked lists.
> +a grace period to elapse, then free the element.  See :ref:`list_rcu`
> +for more information on using RCU with linked lists.
>  
>  Frequently Asked Questions
>  --------------------------
> @@ -49,7 +49,7 @@ Frequently Asked Questions
>  - If I am running on a uniprocessor kernel, which can only do one
>    thing at a time, why should I wait for a grace period?
>  
> -  See the UP.txt file in this directory.
> +  See :ref:`up_rcu` for more information.

This rendered as straight text after "make htmldocs" instead of producing
a link in the HTML output.  The HTML itself is:

	<span class="xref std std-ref">up_rcu</span>

This doesn't look like something that would create a link, though I
freely admit that my HTML is rather outdated.

>  - How can I see where RCU is currently used in the Linux kernel?
>  
> @@ -67,7 +67,7 @@ Frequently Asked Questions
>  
>  - Why the name "RCU"?
>  
> -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has

Same here for list_rcu.

							Thanx, Paul

>    more information on where this name came from, search for
>    "read-copy update" to find it.
>  
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Paul E. McKenney]

On Tue, Jun 25, 2019 at 01:26:26AM -0500, Jiunn Chang wrote:
> Add the following links:
>   - list_rcu
>   - up_rcu
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/rcu.rst | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
> index 000da07d683e..d145decb5c39 100644
> --- a/Documentation/RCU/rcu.rst
> +++ b/Documentation/RCU/rcu.rst
> @@ -10,8 +10,8 @@ A "grace period" must elapse between the two parts, and this grace period
>  must be long enough that any readers accessing the item being deleted have
>  since dropped their references.  For example, an RCU-protected deletion
>  from a linked list would first remove the item from the list, wait for
> -a grace period to elapse, then free the element.  See the listRCU.txt
> -file for more information on using RCU with linked lists.
> +a grace period to elapse, then free the element.  See :ref:`list_rcu`
> +for more information on using RCU with linked lists.
>  
>  Frequently Asked Questions
>  --------------------------
> @@ -49,7 +49,7 @@ Frequently Asked Questions
>  - If I am running on a uniprocessor kernel, which can only do one
>    thing at a time, why should I wait for a grace period?
>  
> -  See the UP.txt file in this directory.
> +  See :ref:`up_rcu` for more information.

This rendered as straight text after "make htmldocs" instead of producing
a link in the HTML output.  The HTML itself is:

	<span class="xref std std-ref">up_rcu</span>

This doesn't look like something that would create a link, though I
freely admit that my HTML is rather outdated.

>  - How can I see where RCU is currently used in the Linux kernel?
>  
> @@ -67,7 +67,7 @@ Frequently Asked Questions
>  
>  - Why the name "RCU"?
>  
> -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has

Same here for list_rcu.

							Thanx, Paul

>    more information on where this name came from, search for
>    "read-copy update" to find it.
>  
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[paulmck]

On Tue, Jun 25, 2019 at 01:26:26AM -0500, Jiunn Chang wrote:
> Add the following links:
>   - list_rcu
>   - up_rcu
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/rcu.rst | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
> index 000da07d683e..d145decb5c39 100644
> --- a/Documentation/RCU/rcu.rst
> +++ b/Documentation/RCU/rcu.rst
> @@ -10,8 +10,8 @@ A "grace period" must elapse between the two parts, and this grace period
>  must be long enough that any readers accessing the item being deleted have
>  since dropped their references.  For example, an RCU-protected deletion
>  from a linked list would first remove the item from the list, wait for
> -a grace period to elapse, then free the element.  See the listRCU.txt
> -file for more information on using RCU with linked lists.
> +a grace period to elapse, then free the element.  See :ref:`list_rcu`
> +for more information on using RCU with linked lists.
>  
>  Frequently Asked Questions
>  --------------------------
> @@ -49,7 +49,7 @@ Frequently Asked Questions
>  - If I am running on a uniprocessor kernel, which can only do one
>    thing at a time, why should I wait for a grace period?
>  
> -  See the UP.txt file in this directory.
> +  See :ref:`up_rcu` for more information.

This rendered as straight text after "make htmldocs" instead of producing
a link in the HTML output.  The HTML itself is:

	<span class="xref std std-ref">up_rcu</span>

This doesn't look like something that would create a link, though I
freely admit that my HTML is rather outdated.

>  - How can I see where RCU is currently used in the Linux kernel?
>  
> @@ -67,7 +67,7 @@ Frequently Asked Questions
>  
>  - Why the name "RCU"?
>  
> -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has

Same here for list_rcu.

							Thanx, Paul

>    more information on where this name came from, search for
>    "read-copy update" to find it.
>  
> -- 
> 2.22.0
> 

Re: [Linux-kernel-mentees][PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Jonathan Corbet]

On Tue, 25 Jun 2019 08:56:23 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> wrote:

> > -  See the UP.txt file in this directory.
> > +  See :ref:`up_rcu` for more information.  
> 
> This rendered as straight text after "make htmldocs" instead of producing
> a link in the HTML output.  The HTML itself is:
> 
> 	<span class="xref std std-ref">up_rcu</span>
> 
> This doesn't look like something that would create a link, though I
> freely admit that my HTML is rather outdated.

The problem is that the reference target isn't called "up_rcu" in the file
itself:

> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..67715a47ae89 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:

Certainly "up_rcu" seems like a better name.  I do believe, though, that
you can also use the title directly:

  See `RCU on Uniprocessor Systems`_ for more information

> >  - How can I see where RCU is currently used in the Linux kernel?
> >  
> > @@ -67,7 +67,7 @@ Frequently Asked Questions
> >  
> >  - Why the name "RCU"?
> >  
> > -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> > +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has  
> 
> Same here for list_rcu.

And the problem is the same, it's list_rcu_doc in the actual source file.

Jiang, as with so many things in software, if you haven't tested it, it
probably doesn't work.  Please actually run "make htmldocs" and look at
the results to be sure that they are what you expect.  (Along those lines,
it would also be good to add the new directory to Documentation/index.rst
so that it gets built with the rest).

Thanks,

jon

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Jonathan Corbet]

On Tue, 25 Jun 2019 08:56:23 -0700
"Paul E. McKenney" <paulmck at linux.ibm.com> wrote:

> > -  See the UP.txt file in this directory.
> > +  See :ref:`up_rcu` for more information.  
> 
> This rendered as straight text after "make htmldocs" instead of producing
> a link in the HTML output.  The HTML itself is:
> 
> 	<span class="xref std std-ref">up_rcu</span>
> 
> This doesn't look like something that would create a link, though I
> freely admit that my HTML is rather outdated.

The problem is that the reference target isn't called "up_rcu" in the file
itself:

> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..67715a47ae89 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:

Certainly "up_rcu" seems like a better name.  I do believe, though, that
you can also use the title directly:

  See `RCU on Uniprocessor Systems`_ for more information

> >  - How can I see where RCU is currently used in the Linux kernel?
> >  
> > @@ -67,7 +67,7 @@ Frequently Asked Questions
> >  
> >  - Why the name "RCU"?
> >  
> > -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> > +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has  
> 
> Same here for list_rcu.

And the problem is the same, it's list_rcu_doc in the actual source file.

Jiang, as with so many things in software, if you haven't tested it, it
probably doesn't work.  Please actually run "make htmldocs" and look at
the results to be sure that they are what you expect.  (Along those lines,
it would also be good to add the new directory to Documentation/index.rst
so that it gets built with the rest).

Thanks,

jon

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[corbet]

On Tue, 25 Jun 2019 08:56:23 -0700
"Paul E. McKenney" <paulmck at linux.ibm.com> wrote:

> > -  See the UP.txt file in this directory.
> > +  See :ref:`up_rcu` for more information.  
> 
> This rendered as straight text after "make htmldocs" instead of producing
> a link in the HTML output.  The HTML itself is:
> 
> 	<span class="xref std std-ref">up_rcu</span>
> 
> This doesn't look like something that would create a link, though I
> freely admit that my HTML is rather outdated.

The problem is that the reference target isn't called "up_rcu" in the file
itself:

> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..67715a47ae89 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:

Certainly "up_rcu" seems like a better name.  I do believe, though, that
you can also use the title directly:

  See `RCU on Uniprocessor Systems`_ for more information

> >  - How can I see where RCU is currently used in the Linux kernel?
> >  
> > @@ -67,7 +67,7 @@ Frequently Asked Questions
> >  
> >  - Why the name "RCU"?
> >  
> > -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> > +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has  
> 
> Same here for list_rcu.

And the problem is the same, it's list_rcu_doc in the actual source file.

Jiang, as with so many things in software, if you haven't tested it, it
probably doesn't work.  Please actually run "make htmldocs" and look at
the results to be sure that they are what you expect.  (Along those lines,
it would also be good to add the new directory to Documentation/index.rst
so that it gets built with the rest).

Thanks,

jon

Re: [Linux-kernel-mentees][PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Paul E. McKenney]

On Tue, Jun 25, 2019 at 03:01:55PM -0600, Jonathan Corbet wrote:
> On Tue, 25 Jun 2019 08:56:23 -0700
> "Paul E. McKenney" <paulmck@linux.ibm.com> wrote:
> 
> > > -  See the UP.txt file in this directory.
> > > +  See :ref:`up_rcu` for more information.  
> > 
> > This rendered as straight text after "make htmldocs" instead of producing
> > a link in the HTML output.  The HTML itself is:
> > 
> > 	<span class="xref std std-ref">up_rcu</span>
> > 
> > This doesn't look like something that would create a link, though I
> > freely admit that my HTML is rather outdated.
> 
> The problem is that the reference target isn't called "up_rcu" in the file
> itself:
> 
> > diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> > index 53bde717017b..67715a47ae89 100644
> > --- a/Documentation/RCU/UP.txt
> > +++ b/Documentation/RCU/UP.txt
> > @@ -1,17 +1,19 @@
> > -RCU on Uniprocessor Systems
> > +.. _up_doc:
> 
> Certainly "up_rcu" seems like a better name.  I do believe, though, that
> you can also use the title directly:
> 
>   See `RCU on Uniprocessor Systems`_ for more information

That does look prettier, though we might want to do something more
directly mapped for people directly reading the .rst files.

> > >  - How can I see where RCU is currently used in the Linux kernel?
> > >  
> > > @@ -67,7 +67,7 @@ Frequently Asked Questions
> > >  
> > >  - Why the name "RCU"?
> > >  
> > > -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> > > +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has  
> > 
> > Same here for list_rcu.
> 
> And the problem is the same, it's list_rcu_doc in the actual source file.
> 
> Jiang, as with so many things in software, if you haven't tested it, it
> probably doesn't work.  Please actually run "make htmldocs" and look at
> the results to be sure that they are what you expect.  (Along those lines,
> it would also be good to add the new directory to Documentation/index.rst
> so that it gets built with the rest).

What Jon said on the "haven't test it, it probably doesn't work" thought.
Sometimes I fear that my own work could be all too accurately modeled as
random mutations with rcutorture providing needed natural selection.  :-/

							Thanx, Paul

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Paul E. McKenney]

On Tue, Jun 25, 2019 at 03:01:55PM -0600, Jonathan Corbet wrote:
> On Tue, 25 Jun 2019 08:56:23 -0700
> "Paul E. McKenney" <paulmck at linux.ibm.com> wrote:
> 
> > > -  See the UP.txt file in this directory.
> > > +  See :ref:`up_rcu` for more information.  
> > 
> > This rendered as straight text after "make htmldocs" instead of producing
> > a link in the HTML output.  The HTML itself is:
> > 
> > 	<span class="xref std std-ref">up_rcu</span>
> > 
> > This doesn't look like something that would create a link, though I
> > freely admit that my HTML is rather outdated.
> 
> The problem is that the reference target isn't called "up_rcu" in the file
> itself:
> 
> > diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> > index 53bde717017b..67715a47ae89 100644
> > --- a/Documentation/RCU/UP.txt
> > +++ b/Documentation/RCU/UP.txt
> > @@ -1,17 +1,19 @@
> > -RCU on Uniprocessor Systems
> > +.. _up_doc:
> 
> Certainly "up_rcu" seems like a better name.  I do believe, though, that
> you can also use the title directly:
> 
>   See `RCU on Uniprocessor Systems`_ for more information

That does look prettier, though we might want to do something more
directly mapped for people directly reading the .rst files.

> > >  - How can I see where RCU is currently used in the Linux kernel?
> > >  
> > > @@ -67,7 +67,7 @@ Frequently Asked Questions
> > >  
> > >  - Why the name "RCU"?
> > >  
> > > -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> > > +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has  
> > 
> > Same here for list_rcu.
> 
> And the problem is the same, it's list_rcu_doc in the actual source file.
> 
> Jiang, as with so many things in software, if you haven't tested it, it
> probably doesn't work.  Please actually run "make htmldocs" and look at
> the results to be sure that they are what you expect.  (Along those lines,
> it would also be good to add the new directory to Documentation/index.rst
> so that it gets built with the rest).

What Jon said on the "haven't test it, it probably doesn't work" thought.
Sometimes I fear that my own work could be all too accurately modeled as
random mutations with rcutorture providing needed natural selection.  :-/

							Thanx, Paul

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[paulmck]

On Tue, Jun 25, 2019 at 03:01:55PM -0600, Jonathan Corbet wrote:
> On Tue, 25 Jun 2019 08:56:23 -0700
> "Paul E. McKenney" <paulmck at linux.ibm.com> wrote:
> 
> > > -  See the UP.txt file in this directory.
> > > +  See :ref:`up_rcu` for more information.  
> > 
> > This rendered as straight text after "make htmldocs" instead of producing
> > a link in the HTML output.  The HTML itself is:
> > 
> > 	<span class="xref std std-ref">up_rcu</span>
> > 
> > This doesn't look like something that would create a link, though I
> > freely admit that my HTML is rather outdated.
> 
> The problem is that the reference target isn't called "up_rcu" in the file
> itself:
> 
> > diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> > index 53bde717017b..67715a47ae89 100644
> > --- a/Documentation/RCU/UP.txt
> > +++ b/Documentation/RCU/UP.txt
> > @@ -1,17 +1,19 @@
> > -RCU on Uniprocessor Systems
> > +.. _up_doc:
> 
> Certainly "up_rcu" seems like a better name.  I do believe, though, that
> you can also use the title directly:
> 
>   See `RCU on Uniprocessor Systems`_ for more information

That does look prettier, though we might want to do something more
directly mapped for people directly reading the .rst files.

> > >  - How can I see where RCU is currently used in the Linux kernel?
> > >  
> > > @@ -67,7 +67,7 @@ Frequently Asked Questions
> > >  
> > >  - Why the name "RCU"?
> > >  
> > > -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> > > +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has  
> > 
> > Same here for list_rcu.
> 
> And the problem is the same, it's list_rcu_doc in the actual source file.
> 
> Jiang, as with so many things in software, if you haven't tested it, it
> probably doesn't work.  Please actually run "make htmldocs" and look at
> the results to be sure that they are what you expect.  (Along those lines,
> it would also be good to add the new directory to Documentation/index.rst
> so that it gets built with the rest).

What Jon said on the "haven't test it, it probably doesn't work" thought.
Sometimes I fear that my own work could be all too accurately modeled as
random mutations with rcutorture providing needed natural selection.  :-/

							Thanx, Paul

Re: [Linux-kernel-mentees][PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Jonathan Corbet]

On Tue, 25 Jun 2019 14:17:40 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> wrote:

> > Certainly "up_rcu" seems like a better name.  I do believe, though, that
> > you can also use the title directly:
> > 
> >   See `RCU on Uniprocessor Systems`_ for more information  
> 
> That does look prettier, though we might want to do something more
> directly mapped for people directly reading the .rst files.

Yeah, the alternative there is to just say "Documentation/RCU/UP.rst".
It's vaporware at the moment, but the plan is to recognize such strings
and link them up automatically in the build process.  It's easy enough to
do, I just have to get around to it.  In anticipation of that, just
putting in the file name is probably the right thing to do.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Jonathan Corbet]

On Tue, 25 Jun 2019 14:17:40 -0700
"Paul E. McKenney" <paulmck at linux.ibm.com> wrote:

> > Certainly "up_rcu" seems like a better name.  I do believe, though, that
> > you can also use the title directly:
> > 
> >   See `RCU on Uniprocessor Systems`_ for more information  
> 
> That does look prettier, though we might want to do something more
> directly mapped for people directly reading the .rst files.

Yeah, the alternative there is to just say "Documentation/RCU/UP.rst".
It's vaporware at the moment, but the plan is to recognize such strings
and link them up automatically in the build process.  It's easy enough to
do, I just have to get around to it.  In anticipation of that, just
putting in the file name is probably the right thing to do.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[corbet]

On Tue, 25 Jun 2019 14:17:40 -0700
"Paul E. McKenney" <paulmck at linux.ibm.com> wrote:

> > Certainly "up_rcu" seems like a better name.  I do believe, though, that
> > you can also use the title directly:
> > 
> >   See `RCU on Uniprocessor Systems`_ for more information  
> 
> That does look prettier, though we might want to do something more
> directly mapped for people directly reading the .rst files.

Yeah, the alternative there is to just say "Documentation/RCU/UP.rst".
It's vaporware at the moment, but the plan is to recognize such strings
and link them up automatically in the build process.  It's easy enough to
do, I just have to get around to it.  In anticipation of that, just
putting in the file name is probably the right thing to do.

Thanks,

jon

Re: [Linux-kernel-mentees][PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Paul E. McKenney]

On Tue, Jun 25, 2019 at 03:40:10PM -0600, Jonathan Corbet wrote:
> On Tue, 25 Jun 2019 14:17:40 -0700
> "Paul E. McKenney" <paulmck@linux.ibm.com> wrote:
> 
> > > Certainly "up_rcu" seems like a better name.  I do believe, though, that
> > > you can also use the title directly:
> > > 
> > >   See `RCU on Uniprocessor Systems`_ for more information  
> > 
> > That does look prettier, though we might want to do something more
> > directly mapped for people directly reading the .rst files.
> 
> Yeah, the alternative there is to just say "Documentation/RCU/UP.rst".
> It's vaporware at the moment, but the plan is to recognize such strings
> and link them up automatically in the build process.  It's easy enough to
> do, I just have to get around to it.  In anticipation of that, just
> putting in the file name is probably the right thing to do.

Works for me!  Easy enough to cut-and-paste the filename into the
corresponding portion of the URL, in the meantime.

							Thanx, Paul

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[Paul E. McKenney]

On Tue, Jun 25, 2019 at 03:40:10PM -0600, Jonathan Corbet wrote:
> On Tue, 25 Jun 2019 14:17:40 -0700
> "Paul E. McKenney" <paulmck at linux.ibm.com> wrote:
> 
> > > Certainly "up_rcu" seems like a better name.  I do believe, though, that
> > > you can also use the title directly:
> > > 
> > >   See `RCU on Uniprocessor Systems`_ for more information  
> > 
> > That does look prettier, though we might want to do something more
> > directly mapped for people directly reading the .rst files.
> 
> Yeah, the alternative there is to just say "Documentation/RCU/UP.rst".
> It's vaporware at the moment, but the plan is to recognize such strings
> and link them up automatically in the build process.  It's easy enough to
> do, I just have to get around to it.  In anticipation of that, just
> putting in the file name is probably the right thing to do.

Works for me!  Easy enough to cut-and-paste the filename into the
corresponding portion of the URL, in the meantime.

							Thanx, Paul

[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[paulmck]

On Tue, Jun 25, 2019 at 03:40:10PM -0600, Jonathan Corbet wrote:
> On Tue, 25 Jun 2019 14:17:40 -0700
> "Paul E. McKenney" <paulmck at linux.ibm.com> wrote:
> 
> > > Certainly "up_rcu" seems like a better name.  I do believe, though, that
> > > you can also use the title directly:
> > > 
> > >   See `RCU on Uniprocessor Systems`_ for more information  
> > 
> > That does look prettier, though we might want to do something more
> > directly mapped for people directly reading the .rst files.
> 
> Yeah, the alternative there is to just say "Documentation/RCU/UP.rst".
> It's vaporware at the moment, but the plan is to recognize such strings
> and link them up automatically in the build process.  It's easy enough to
> do, I just have to get around to it.  In anticipation of that, just
> putting in the file name is probably the right thing to do.

Works for me!  Easy enough to cut-and-paste the filename into the
corresponding portion of the URL, in the meantime.

							Thanx, Paul

[Linux-kernel-mentees][PATCH v3 6/6] Documentation: RCU: Add TOC tree hooks

[Jiunn Chang]

Add TOC tree hooks for:
  - rcu
  - list_rcu
  - up_rcu

Signed-off-by: Jiunn Chang <c0d1n61at3@gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..8349dd598bb8
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   list_rcu
+   up_rcu
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 6/6] Documentation: RCU: Add TOC tree hooks

[Jiunn Chang]

Add TOC tree hooks for:
  - rcu
  - list_rcu
  - up_rcu

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..8349dd598bb8
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   list_rcu
+   up_rcu
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v3 6/6] Documentation: RCU: Add TOC tree hooks

[c0d1n61at3]

Add TOC tree hooks for:
  - rcu
  - list_rcu
  - up_rcu

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..8349dd598bb8
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,19 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+   list_rcu
+   up_rcu
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST

[c0d1n61at3]

ReST markup and TOC tree hook.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst |  17 ++++++
 Documentation/RCU/rcu.txt   | 114 ++++++++++++++++++------------------
 2 files changed, 75 insertions(+), 56 deletions(-)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..bc8cd42a91cc
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,17 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..2b93b128a6fd 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,8 @@
-RCU Concepts
+.. _rcu_doc:
 
+============
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -11,79 +14,78 @@ from a linked list would first remove the item from the list, wait for
 a grace period to elapse, then free the element.  See the listRCU.txt
 file for more information on using RCU with linked lists.
 
-
 Frequently Asked Questions
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the UP.txt file in this directory.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST

[Jiunn Chang]

ReST markup and TOC tree hook.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst |  17 ++++++
 Documentation/RCU/rcu.txt   | 114 ++++++++++++++++++------------------
 2 files changed, 75 insertions(+), 56 deletions(-)
 create mode 100644 Documentation/RCU/index.rst

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
new file mode 100644
index 000000000000..bc8cd42a91cc
--- /dev/null
+++ b/Documentation/RCU/index.rst
@@ -0,0 +1,17 @@
+.. _rcu_concepts:
+
+============
+RCU concepts
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   rcu
+
+.. only:: subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
index c818cf65c5a9..2b93b128a6fd 100644
--- a/Documentation/RCU/rcu.txt
+++ b/Documentation/RCU/rcu.txt
@@ -1,5 +1,8 @@
-RCU Concepts
+.. _rcu_doc:
 
+============
+RCU Concepts
+============
 
 The basic idea behind RCU (read-copy update) is to split destructive
 operations into two parts, one that prevents anyone from seeing the data
@@ -11,79 +14,78 @@ from a linked list would first remove the item from the list, wait for
 a grace period to elapse, then free the element.  See the listRCU.txt
 file for more information on using RCU with linked lists.
 
-
 Frequently Asked Questions
 
-o	Why would anyone want to use RCU?
+- Why would anyone want to use RCU?
 
-	The advantage of RCU's two-part approach is that RCU readers need
-	not acquire any locks, perform any atomic instructions, write to
-	shared memory, or (on CPUs other than Alpha) execute any memory
-	barriers.  The fact that these operations are quite expensive
-	on modern CPUs is what gives RCU its performance advantages
-	in read-mostly situations.  The fact that RCU readers need not
-	acquire locks can also greatly simplify deadlock-avoidance code.
+  The advantage of RCU's two-part approach is that RCU readers need
+  not acquire any locks, perform any atomic instructions, write to
+  shared memory, or (on CPUs other than Alpha) execute any memory
+  barriers.  The fact that these operations are quite expensive
+  on modern CPUs is what gives RCU its performance advantages
+  in read-mostly situations.  The fact that RCU readers need not
+  acquire locks can also greatly simplify deadlock-avoidance code.
 
-o	How can the updater tell when a grace period has completed
-	if the RCU readers give no indication when they are done?
+- How can the updater tell when a grace period has completed
+  if the RCU readers give no indication when they are done?
 
-	Just as with spinlocks, RCU readers are not permitted to
-	block, switch to user-mode execution, or enter the idle loop.
-	Therefore, as soon as a CPU is seen passing through any of these
-	three states, we know that that CPU has exited any previous RCU
-	read-side critical sections.  So, if we remove an item from a
-	linked list, and then wait until all CPUs have switched context,
-	executed in user mode, or executed in the idle loop, we can
-	safely free up that item.
+  Just as with spinlocks, RCU readers are not permitted to
+  block, switch to user-mode execution, or enter the idle loop.
+  Therefore, as soon as a CPU is seen passing through any of these
+  three states, we know that that CPU has exited any previous RCU
+  read-side critical sections.  So, if we remove an item from a
+  linked list, and then wait until all CPUs have switched context,
+  executed in user mode, or executed in the idle loop, we can
+  safely free up that item.
 
-	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
-	same effect, but require that the readers manipulate CPU-local
-	counters.  These counters allow limited types of blocking within
-	RCU read-side critical sections.  SRCU also uses CPU-local
-	counters, and permits general blocking within RCU read-side
-	critical sections.  These variants of RCU detect grace periods
-	by sampling these counters.
+  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
+  same effect, but require that the readers manipulate CPU-local
+  counters.  These counters allow limited types of blocking within
+  RCU read-side critical sections.  SRCU also uses CPU-local
+  counters, and permits general blocking within RCU read-side
+  critical sections.  These variants of RCU detect grace periods
+  by sampling these counters.
 
-o	If I am running on a uniprocessor kernel, which can only do one
-	thing at a time, why should I wait for a grace period?
+- If I am running on a uniprocessor kernel, which can only do one
+  thing at a time, why should I wait for a grace period?
 
-	See the UP.txt file in this directory.
+  See the UP.txt file in this directory.
 
-o	How can I see where RCU is currently used in the Linux kernel?
+- How can I see where RCU is currently used in the Linux kernel?
 
-	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
-	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
-	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
-	"synchronize_srcu", and the other RCU primitives.  Or grab one
-	of the cscope databases from:
+  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
+  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
+  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
+  "synchronize_srcu", and the other RCU primitives.  Or grab one
+  of the cscope databases from:
 
-	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
+  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
 
-o	What guidelines should I follow when writing code that uses RCU?
+- What guidelines should I follow when writing code that uses RCU?
 
-	See the checklist.txt file in this directory.
+  See the checklist.txt file in this directory.
 
-o	Why the name "RCU"?
+- Why the name "RCU"?
 
-	"RCU" stands for "read-copy update".  The file listRCU.txt has
-	more information on where this name came from, search for
-	"read-copy update" to find it.
+  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  more information on where this name came from, search for
+  "read-copy update" to find it.
 
-o	I hear that RCU is patented?  What is with that?
+- 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 RTFP.txt 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
-	available (http://liburcu.org/).
+  Yes, it is.  There are several known patents related to RCU,
+  search for the string "Patent" in RTFP.txt 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
+  available (http://liburcu.org/).
 
-o	I hear that RCU needs work in order to support realtime kernels?
+- I hear that RCU needs work in order to support realtime kernels?
 
-	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
-	kernel configuration parameter.
+  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
+  kernel configuration parameter.
 
-o	Where can I find more information on RCU?
+- Where can I find more information on RCU?
 
-	See the RTFP.txt file in this directory.
-	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
+  See the RTFP.txt file in this directory.
+  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST

[joel]

On Sun, Jun 23, 2019 at 03:14:07AM -0500, Jiunn Chang wrote:
> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>

This one LGTM.

Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>

thanks,

 - Joel

> ---
>  Documentation/RCU/index.rst |  17 ++++++
>  Documentation/RCU/rcu.txt   | 114 ++++++++++++++++++------------------
>  2 files changed, 75 insertions(+), 56 deletions(-)
>  create mode 100644 Documentation/RCU/index.rst
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> new file mode 100644
> index 000000000000..bc8cd42a91cc
> --- /dev/null
> +++ b/Documentation/RCU/index.rst
> @@ -0,0 +1,17 @@
> +.. _rcu_concepts:
> +
> +============
> +RCU concepts
> +============
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   rcu
> +
> +.. only:: subproject and html
> +
> +   Indices
> +   =======
> +
> +   * :ref:`genindex`
> diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
> index c818cf65c5a9..2b93b128a6fd 100644
> --- a/Documentation/RCU/rcu.txt
> +++ b/Documentation/RCU/rcu.txt
> @@ -1,5 +1,8 @@
> -RCU Concepts
> +.. _rcu_doc:
>  
> +============
> +RCU Concepts
> +============
>  
>  The basic idea behind RCU (read-copy update) is to split destructive
>  operations into two parts, one that prevents anyone from seeing the data
> @@ -11,79 +14,78 @@ from a linked list would first remove the item from the list, wait for
>  a grace period to elapse, then free the element.  See the listRCU.txt
>  file for more information on using RCU with linked lists.
>  
> -
>  Frequently Asked Questions
>  
> -o	Why would anyone want to use RCU?
> +- Why would anyone want to use RCU?
>  
> -	The advantage of RCU's two-part approach is that RCU readers need
> -	not acquire any locks, perform any atomic instructions, write to
> -	shared memory, or (on CPUs other than Alpha) execute any memory
> -	barriers.  The fact that these operations are quite expensive
> -	on modern CPUs is what gives RCU its performance advantages
> -	in read-mostly situations.  The fact that RCU readers need not
> -	acquire locks can also greatly simplify deadlock-avoidance code.
> +  The advantage of RCU's two-part approach is that RCU readers need
> +  not acquire any locks, perform any atomic instructions, write to
> +  shared memory, or (on CPUs other than Alpha) execute any memory
> +  barriers.  The fact that these operations are quite expensive
> +  on modern CPUs is what gives RCU its performance advantages
> +  in read-mostly situations.  The fact that RCU readers need not
> +  acquire locks can also greatly simplify deadlock-avoidance code.
>  
> -o	How can the updater tell when a grace period has completed
> -	if the RCU readers give no indication when they are done?
> +- How can the updater tell when a grace period has completed
> +  if the RCU readers give no indication when they are done?
>  
> -	Just as with spinlocks, RCU readers are not permitted to
> -	block, switch to user-mode execution, or enter the idle loop.
> -	Therefore, as soon as a CPU is seen passing through any of these
> -	three states, we know that that CPU has exited any previous RCU
> -	read-side critical sections.  So, if we remove an item from a
> -	linked list, and then wait until all CPUs have switched context,
> -	executed in user mode, or executed in the idle loop, we can
> -	safely free up that item.
> +  Just as with spinlocks, RCU readers are not permitted to
> +  block, switch to user-mode execution, or enter the idle loop.
> +  Therefore, as soon as a CPU is seen passing through any of these
> +  three states, we know that that CPU has exited any previous RCU
> +  read-side critical sections.  So, if we remove an item from a
> +  linked list, and then wait until all CPUs have switched context,
> +  executed in user mode, or executed in the idle loop, we can
> +  safely free up that item.
>  
> -	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
> -	same effect, but require that the readers manipulate CPU-local
> -	counters.  These counters allow limited types of blocking within
> -	RCU read-side critical sections.  SRCU also uses CPU-local
> -	counters, and permits general blocking within RCU read-side
> -	critical sections.  These variants of RCU detect grace periods
> -	by sampling these counters.
> +  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
> +  same effect, but require that the readers manipulate CPU-local
> +  counters.  These counters allow limited types of blocking within
> +  RCU read-side critical sections.  SRCU also uses CPU-local
> +  counters, and permits general blocking within RCU read-side
> +  critical sections.  These variants of RCU detect grace periods
> +  by sampling these counters.
>  
> -o	If I am running on a uniprocessor kernel, which can only do one
> -	thing at a time, why should I wait for a grace period?
> +- If I am running on a uniprocessor kernel, which can only do one
> +  thing at a time, why should I wait for a grace period?
>  
> -	See the UP.txt file in this directory.
> +  See the UP.txt file in this directory.
>  
> -o	How can I see where RCU is currently used in the Linux kernel?
> +- How can I see where RCU is currently used in the Linux kernel?
>  
> -	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
> -	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
> -	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
> -	"synchronize_srcu", and the other RCU primitives.  Or grab one
> -	of the cscope databases from:
> +  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
> +  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
> +  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
> +  "synchronize_srcu", and the other RCU primitives.  Or grab one
> +  of the cscope databases from:
>  
> -	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
> +  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
>  
> -o	What guidelines should I follow when writing code that uses RCU?
> +- What guidelines should I follow when writing code that uses RCU?
>  
> -	See the checklist.txt file in this directory.
> +  See the checklist.txt file in this directory.
>  
> -o	Why the name "RCU"?
> +- Why the name "RCU"?
>  
> -	"RCU" stands for "read-copy update".  The file listRCU.txt has
> -	more information on where this name came from, search for
> -	"read-copy update" to find it.
> +  "RCU" stands for "read-copy update".  The file listRCU.txt has
> +  more information on where this name came from, search for
> +  "read-copy update" to find it.
>  
> -o	I hear that RCU is patented?  What is with that?
> +- 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 RTFP.txt 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
> -	available (http://liburcu.org/).
> +  Yes, it is.  There are several known patents related to RCU,
> +  search for the string "Patent" in RTFP.txt 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
> +  available (http://liburcu.org/).
>  
> -o	I hear that RCU needs work in order to support realtime kernels?
> +- I hear that RCU needs work in order to support realtime kernels?
>  
> -	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
> -	kernel configuration parameter.
> +  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
> +  kernel configuration parameter.
>  
> -o	Where can I find more information on RCU?
> +- Where can I find more information on RCU?
>  
> -	See the RTFP.txt file in this directory.
> -	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
> +  See the RTFP.txt file in this directory.
> +  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST

[Joel Fernandes]

On Sun, Jun 23, 2019 at 03:14:07AM -0500, Jiunn Chang wrote:
> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>

This one LGTM.

Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>

thanks,

 - Joel

> ---
>  Documentation/RCU/index.rst |  17 ++++++
>  Documentation/RCU/rcu.txt   | 114 ++++++++++++++++++------------------
>  2 files changed, 75 insertions(+), 56 deletions(-)
>  create mode 100644 Documentation/RCU/index.rst
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> new file mode 100644
> index 000000000000..bc8cd42a91cc
> --- /dev/null
> +++ b/Documentation/RCU/index.rst
> @@ -0,0 +1,17 @@
> +.. _rcu_concepts:
> +
> +============
> +RCU concepts
> +============
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   rcu
> +
> +.. only:: subproject and html
> +
> +   Indices
> +   =======
> +
> +   * :ref:`genindex`
> diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.txt
> index c818cf65c5a9..2b93b128a6fd 100644
> --- a/Documentation/RCU/rcu.txt
> +++ b/Documentation/RCU/rcu.txt
> @@ -1,5 +1,8 @@
> -RCU Concepts
> +.. _rcu_doc:
>  
> +============
> +RCU Concepts
> +============
>  
>  The basic idea behind RCU (read-copy update) is to split destructive
>  operations into two parts, one that prevents anyone from seeing the data
> @@ -11,79 +14,78 @@ from a linked list would first remove the item from the list, wait for
>  a grace period to elapse, then free the element.  See the listRCU.txt
>  file for more information on using RCU with linked lists.
>  
> -
>  Frequently Asked Questions
>  
> -o	Why would anyone want to use RCU?
> +- Why would anyone want to use RCU?
>  
> -	The advantage of RCU's two-part approach is that RCU readers need
> -	not acquire any locks, perform any atomic instructions, write to
> -	shared memory, or (on CPUs other than Alpha) execute any memory
> -	barriers.  The fact that these operations are quite expensive
> -	on modern CPUs is what gives RCU its performance advantages
> -	in read-mostly situations.  The fact that RCU readers need not
> -	acquire locks can also greatly simplify deadlock-avoidance code.
> +  The advantage of RCU's two-part approach is that RCU readers need
> +  not acquire any locks, perform any atomic instructions, write to
> +  shared memory, or (on CPUs other than Alpha) execute any memory
> +  barriers.  The fact that these operations are quite expensive
> +  on modern CPUs is what gives RCU its performance advantages
> +  in read-mostly situations.  The fact that RCU readers need not
> +  acquire locks can also greatly simplify deadlock-avoidance code.
>  
> -o	How can the updater tell when a grace period has completed
> -	if the RCU readers give no indication when they are done?
> +- How can the updater tell when a grace period has completed
> +  if the RCU readers give no indication when they are done?
>  
> -	Just as with spinlocks, RCU readers are not permitted to
> -	block, switch to user-mode execution, or enter the idle loop.
> -	Therefore, as soon as a CPU is seen passing through any of these
> -	three states, we know that that CPU has exited any previous RCU
> -	read-side critical sections.  So, if we remove an item from a
> -	linked list, and then wait until all CPUs have switched context,
> -	executed in user mode, or executed in the idle loop, we can
> -	safely free up that item.
> +  Just as with spinlocks, RCU readers are not permitted to
> +  block, switch to user-mode execution, or enter the idle loop.
> +  Therefore, as soon as a CPU is seen passing through any of these
> +  three states, we know that that CPU has exited any previous RCU
> +  read-side critical sections.  So, if we remove an item from a
> +  linked list, and then wait until all CPUs have switched context,
> +  executed in user mode, or executed in the idle loop, we can
> +  safely free up that item.
>  
> -	Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
> -	same effect, but require that the readers manipulate CPU-local
> -	counters.  These counters allow limited types of blocking within
> -	RCU read-side critical sections.  SRCU also uses CPU-local
> -	counters, and permits general blocking within RCU read-side
> -	critical sections.  These variants of RCU detect grace periods
> -	by sampling these counters.
> +  Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
> +  same effect, but require that the readers manipulate CPU-local
> +  counters.  These counters allow limited types of blocking within
> +  RCU read-side critical sections.  SRCU also uses CPU-local
> +  counters, and permits general blocking within RCU read-side
> +  critical sections.  These variants of RCU detect grace periods
> +  by sampling these counters.
>  
> -o	If I am running on a uniprocessor kernel, which can only do one
> -	thing at a time, why should I wait for a grace period?
> +- If I am running on a uniprocessor kernel, which can only do one
> +  thing at a time, why should I wait for a grace period?
>  
> -	See the UP.txt file in this directory.
> +  See the UP.txt file in this directory.
>  
> -o	How can I see where RCU is currently used in the Linux kernel?
> +- How can I see where RCU is currently used in the Linux kernel?
>  
> -	Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
> -	"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
> -	"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
> -	"synchronize_srcu", and the other RCU primitives.  Or grab one
> -	of the cscope databases from:
> +  Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
> +  "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
> +  "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
> +  "synchronize_srcu", and the other RCU primitives.  Or grab one
> +  of the cscope databases from:
>  
> -	http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
> +  (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
>  
> -o	What guidelines should I follow when writing code that uses RCU?
> +- What guidelines should I follow when writing code that uses RCU?
>  
> -	See the checklist.txt file in this directory.
> +  See the checklist.txt file in this directory.
>  
> -o	Why the name "RCU"?
> +- Why the name "RCU"?
>  
> -	"RCU" stands for "read-copy update".  The file listRCU.txt has
> -	more information on where this name came from, search for
> -	"read-copy update" to find it.
> +  "RCU" stands for "read-copy update".  The file listRCU.txt has
> +  more information on where this name came from, search for
> +  "read-copy update" to find it.
>  
> -o	I hear that RCU is patented?  What is with that?
> +- 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 RTFP.txt 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
> -	available (http://liburcu.org/).
> +  Yes, it is.  There are several known patents related to RCU,
> +  search for the string "Patent" in RTFP.txt 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
> +  available (http://liburcu.org/).
>  
> -o	I hear that RCU needs work in order to support realtime kernels?
> +- I hear that RCU needs work in order to support realtime kernels?
>  
> -	Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
> -	kernel configuration parameter.
> +  Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
> +  kernel configuration parameter.
>  
> -o	Where can I find more information on RCU?
> +- Where can I find more information on RCU?
>  
> -	See the RTFP.txt file in this directory.
> -	Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
> +  See the RTFP.txt file in this directory.
> +  Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST

[c0d1n61at3]

Rename RCU basic concepts txt file to rst.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{rcu.txt => rcu.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST

[Jiunn Chang]

Rename RCU basic concepts txt file to rst.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{rcu.txt => rcu.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)

diff --git a/Documentation/RCU/rcu.txt b/Documentation/RCU/rcu.rst
similarity index 100%
rename from Documentation/RCU/rcu.txt
rename to Documentation/RCU/rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST

[c0d1n61at3]

ReST markup and TOC tree hook.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst   |  1 +
 Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++--------------
 2 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index bc8cd42a91cc..5a19c3642e88 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -8,6 +8,7 @@ RCU concepts
    :maxdepth: 1
 
    rcu
+   list_rcu
 
 .. only:: subproject and html
 
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..f786cd82c6a7 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,14 +1,16 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
-("struct list_head" in list.h).  One big advantage of this approach
+(*struct list_head* in ``list.h``).  One big advantage of this approach
 is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -234,10 +236,12 @@ return holding the per-entry spinlock, as ipc_lock() does in fact do.
 Quick Quiz:  Why does the search function need to return holding the
 	per-entry lock for this deleted-flag technique to be helpful?
 
+:ref:`answer_quick_quiz`
+
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +272,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +294,10 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
+.. _answer_quick_quiz:
 
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,7 +308,6 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
-
 Answer to Quick Quiz
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST

[Jiunn Chang]

ReST markup and TOC tree hook.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/index.rst   |  1 +
 Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++--------------
 2 files changed, 20 insertions(+), 14 deletions(-)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index bc8cd42a91cc..5a19c3642e88 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -8,6 +8,7 @@ RCU concepts
    :maxdepth: 1
 
    rcu
+   list_rcu
 
 .. only:: subproject and html
 
diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
index adb5a3782846..f786cd82c6a7 100644
--- a/Documentation/RCU/listRCU.txt
+++ b/Documentation/RCU/listRCU.txt
@@ -1,14 +1,16 @@
-Using RCU to Protect Read-Mostly Linked Lists
+.. _list_rcu_doc:
 
+Using RCU to Protect Read-Mostly Linked Lists
+=============================================
 
 One of the best applications of RCU is to protect read-mostly linked lists
-("struct list_head" in list.h).  One big advantage of this approach
+(*struct list_head* in ``list.h``).  One big advantage of this approach
 is that all of the required memory barriers are included for you in
 the list macros.  This document describes several applications of RCU,
 with the best fits first.
 
-
 Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
+----------------------------------------------------------------------
 
 The best applications are cases where, if reader-writer locking were
 used, the read-side lock would be dropped before taking any action
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the
 system-call auditing support.  For example, a reader-writer locked
-implementation of audit_filter_task() might be as follows:
+implementation of audit_filter_task() might be as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
 on, the list may well have been modified.  This makes sense, since if
 you are turning auditing off, it is OK to audit a few extra system calls.
 
-This means that RCU can be easily applied to the read side, as follows:
+This means that RCU can be easily applied to the read side, as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
 insert the read-side memory barriers that are required on DEC Alpha CPUs.
 
 The changes to the update side are also straightforward.  A reader-writer
-lock might be used as follows for deletion and insertion:
+lock might be used as follows for deletion and insertion::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
 		return 0;
 	}
 
-Following are the RCU equivalents for these two functions:
+Following are the RCU equivalents for these two functions::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
 So, when readers can tolerate stale data and when entries are either added
 or deleted, without in-place modification, it is very easy to use RCU!
 
-
 Example 2: Handling In-Place Updates
+------------------------------------
 
 The system-call auditing code does not update auditing rules in place.
 However, if it did, reader-writer-locked code to do so might look as
 follows (presumably, the field_count is only permitted to decrease,
-otherwise, the added fields would need to be filled in):
+otherwise, the added fields would need to be filled in)::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
 The RCU version creates a copy, updates the copy, then replaces the old
 entry with the newly updated entry.  This sequence of actions, allowing
 concurrent reads while doing a copy to perform an update, is what gives
-RCU ("read-copy update") its name.  The RCU code is as follows:
+RCU ("read-copy update") its name.  The RCU code is as follows::
 
 	static inline int audit_upd_rule(struct audit_rule *rule,
 					 struct list_head *list,
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
 Again, this assumes that the caller holds audit_netlink_sem.  Normally,
 the reader-writer lock would become a spinlock in this sort of code.
 
-
 Example 3: Eliminating Stale Data
+---------------------------------
 
 The auditing examples above tolerate stale data, as do most algorithms
 that are tracking external state.  Because there is a delay from the
@@ -234,10 +236,12 @@ return holding the per-entry spinlock, as ipc_lock() does in fact do.
 Quick Quiz:  Why does the search function need to return holding the
 	per-entry lock for this deleted-flag technique to be helpful?
 
+:ref:`answer_quick_quiz`
+
 If the system-call audit module were to ever need to reject stale data,
 one way to accomplish this would be to add a "deleted" flag and a "lock"
 spinlock to the audit_entry structure, and modify audit_filter_task()
-as follows:
+as follows::
 
 	static enum audit_state audit_filter_task(struct task_struct *tsk)
 	{
@@ -268,7 +272,7 @@ audit_upd_rule() would need additional memory barriers to ensure
 that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
-flag under the spinlock as follows:
+flag under the spinlock as follows::
 
 	static inline int audit_del_rule(struct audit_rule *rule,
 					 struct list_head *list)
@@ -290,8 +294,10 @@ flag under the spinlock as follows:
 		return -EFAULT;		/* No matching rule */
 	}
 
+.. _answer_quick_quiz:
 
 Summary
+-------
 
 Read-mostly list-based data structures that can tolerate stale data are
 the most amenable to use of RCU.  The simplest case is where entries are
@@ -302,7 +308,6 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
 in conjunction with a per-entry spinlock in order to allow the search
 function to reject newly deleted data.
 
-
 Answer to Quick Quiz
 	Why does the search function need to return holding the per-entry
 	lock for this deleted-flag technique to be helpful?
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST

[joel]

On Sun, Jun 23, 2019 at 03:14:09AM -0500, Jiunn Chang wrote:
> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/index.rst   |  1 +
>  Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++--------------
>  2 files changed, 20 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index bc8cd42a91cc..5a19c3642e88 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 1
>  
>     rcu
> +   list_rcu
>  
>  .. only:: subproject and html
>  
> diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
> index adb5a3782846..f786cd82c6a7 100644
> --- a/Documentation/RCU/listRCU.txt
> +++ b/Documentation/RCU/listRCU.txt
> @@ -1,14 +1,16 @@
> -Using RCU to Protect Read-Mostly Linked Lists
> +.. _list_rcu_doc:
>  
> +Using RCU to Protect Read-Mostly Linked Lists
> +=============================================
>  
>  One of the best applications of RCU is to protect read-mostly linked lists
> -("struct list_head" in list.h).  One big advantage of this approach
> +(*struct list_head* in ``list.h``).  One big advantage of this approach
>  is that all of the required memory barriers are included for you in
>  the list macros.  This document describes several applications of RCU,
>  with the best fits first.
>  
> -
>  Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
> +----------------------------------------------------------------------
>  
>  The best applications are cases where, if reader-writer locking were
>  used, the read-side lock would be dropped before taking any action
> @@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
>  
>  A straightforward example of this use of RCU may be found in the
>  system-call auditing support.  For example, a reader-writer locked
> -implementation of audit_filter_task() might be as follows:
> +implementation of audit_filter_task() might be as follows::
>  
>  	static enum audit_state audit_filter_task(struct task_struct *tsk)
>  	{
> @@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
>  on, the list may well have been modified.  This makes sense, since if
>  you are turning auditing off, it is OK to audit a few extra system calls.
>  
> -This means that RCU can be easily applied to the read side, as follows:
> +This means that RCU can be easily applied to the read side, as follows::
>  
>  	static enum audit_state audit_filter_task(struct task_struct *tsk)
>  	{
> @@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
>  insert the read-side memory barriers that are required on DEC Alpha CPUs.
>  
>  The changes to the update side are also straightforward.  A reader-writer
> -lock might be used as follows for deletion and insertion:
> +lock might be used as follows for deletion and insertion::
>  
>  	static inline int audit_del_rule(struct audit_rule *rule,
>  					 struct list_head *list)
> @@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
>  		return 0;
>  	}
>  
> -Following are the RCU equivalents for these two functions:
> +Following are the RCU equivalents for these two functions::
>  
>  	static inline int audit_del_rule(struct audit_rule *rule,
>  					 struct list_head *list)
> @@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
>  So, when readers can tolerate stale data and when entries are either added
>  or deleted, without in-place modification, it is very easy to use RCU!
>  
> -
>  Example 2: Handling In-Place Updates
> +------------------------------------
>  
>  The system-call auditing code does not update auditing rules in place.
>  However, if it did, reader-writer-locked code to do so might look as
>  follows (presumably, the field_count is only permitted to decrease,
> -otherwise, the added fields would need to be filled in):
> +otherwise, the added fields would need to be filled in)::
>  
>  	static inline int audit_upd_rule(struct audit_rule *rule,
>  					 struct list_head *list,
> @@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
>  The RCU version creates a copy, updates the copy, then replaces the old
>  entry with the newly updated entry.  This sequence of actions, allowing
>  concurrent reads while doing a copy to perform an update, is what gives
> -RCU ("read-copy update") its name.  The RCU code is as follows:
> +RCU ("read-copy update") its name.  The RCU code is as follows::
>  
>  	static inline int audit_upd_rule(struct audit_rule *rule,
>  					 struct list_head *list,
> @@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
>  Again, this assumes that the caller holds audit_netlink_sem.  Normally,
>  the reader-writer lock would become a spinlock in this sort of code.
>  
> -
>  Example 3: Eliminating Stale Data
> +---------------------------------
>  
>  The auditing examples above tolerate stale data, as do most algorithms
>  that are tracking external state.  Because there is a delay from the
> @@ -234,10 +236,12 @@ return holding the per-entry spinlock, as ipc_lock() does in fact do.
>  Quick Quiz:  Why does the search function need to return holding the
>  	per-entry lock for this deleted-flag technique to be helpful?
>  
> +:ref:`answer_quick_quiz`
> +
>  If the system-call audit module were to ever need to reject stale data,
>  one way to accomplish this would be to add a "deleted" flag and a "lock"
>  spinlock to the audit_entry structure, and modify audit_filter_task()
> -as follows:
> +as follows::
>  
>  	static enum audit_state audit_filter_task(struct task_struct *tsk)
>  	{
> @@ -268,7 +272,7 @@ audit_upd_rule() would need additional memory barriers to ensure
>  that the list_add_rcu() was really executed before the list_del_rcu().
>  
>  The audit_del_rule() function would need to set the "deleted"
> -flag under the spinlock as follows:
> +flag under the spinlock as follows::
>  
>  	static inline int audit_del_rule(struct audit_rule *rule,
>  					 struct list_head *list)
> @@ -290,8 +294,10 @@ flag under the spinlock as follows:
>  		return -EFAULT;		/* No matching rule */
>  	}
>  
> +.. _answer_quick_quiz:

Should the _answer_quick_quiz label below where 'Answer to Quick Quiz' is below?


>  
>  Summary
> +-------
>  
>  Read-mostly list-based data structures that can tolerate stale data are
>  the most amenable to use of RCU.  The simplest case is where entries are
> @@ -302,7 +308,6 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
>  in conjunction with a per-entry spinlock in order to allow the search
>  function to reject newly deleted data.
>  

That is, should it be here?

> -
>  Answer to Quick Quiz
>  	Why does the search function need to return holding the per-entry
>  	lock for this deleted-flag technique to be helpful?
> -- 
> 2.22.0
> 

thanks,

 - Joel

[Linux-kernel-mentees] [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST

[Joel Fernandes]

On Sun, Jun 23, 2019 at 03:14:09AM -0500, Jiunn Chang wrote:
> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/index.rst   |  1 +
>  Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++--------------
>  2 files changed, 20 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index bc8cd42a91cc..5a19c3642e88 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 1
>  
>     rcu
> +   list_rcu
>  
>  .. only:: subproject and html
>  
> diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
> index adb5a3782846..f786cd82c6a7 100644
> --- a/Documentation/RCU/listRCU.txt
> +++ b/Documentation/RCU/listRCU.txt
> @@ -1,14 +1,16 @@
> -Using RCU to Protect Read-Mostly Linked Lists
> +.. _list_rcu_doc:
>  
> +Using RCU to Protect Read-Mostly Linked Lists
> +=============================================
>  
>  One of the best applications of RCU is to protect read-mostly linked lists
> -("struct list_head" in list.h).  One big advantage of this approach
> +(*struct list_head* in ``list.h``).  One big advantage of this approach
>  is that all of the required memory barriers are included for you in
>  the list macros.  This document describes several applications of RCU,
>  with the best fits first.
>  
> -
>  Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
> +----------------------------------------------------------------------
>  
>  The best applications are cases where, if reader-writer locking were
>  used, the read-side lock would be dropped before taking any action
> @@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
>  
>  A straightforward example of this use of RCU may be found in the
>  system-call auditing support.  For example, a reader-writer locked
> -implementation of audit_filter_task() might be as follows:
> +implementation of audit_filter_task() might be as follows::
>  
>  	static enum audit_state audit_filter_task(struct task_struct *tsk)
>  	{
> @@ -48,7 +50,7 @@ the corresponding value is returned.  By the time that this value is acted
>  on, the list may well have been modified.  This makes sense, since if
>  you are turning auditing off, it is OK to audit a few extra system calls.
>  
> -This means that RCU can be easily applied to the read side, as follows:
> +This means that RCU can be easily applied to the read side, as follows::
>  
>  	static enum audit_state audit_filter_task(struct task_struct *tsk)
>  	{
> @@ -73,7 +75,7 @@ become list_for_each_entry_rcu().  The _rcu() list-traversal primitives
>  insert the read-side memory barriers that are required on DEC Alpha CPUs.
>  
>  The changes to the update side are also straightforward.  A reader-writer
> -lock might be used as follows for deletion and insertion:
> +lock might be used as follows for deletion and insertion::
>  
>  	static inline int audit_del_rule(struct audit_rule *rule,
>  					 struct list_head *list)
> @@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
>  		return 0;
>  	}
>  
> -Following are the RCU equivalents for these two functions:
> +Following are the RCU equivalents for these two functions::
>  
>  	static inline int audit_del_rule(struct audit_rule *rule,
>  					 struct list_head *list)
> @@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
>  So, when readers can tolerate stale data and when entries are either added
>  or deleted, without in-place modification, it is very easy to use RCU!
>  
> -
>  Example 2: Handling In-Place Updates
> +------------------------------------
>  
>  The system-call auditing code does not update auditing rules in place.
>  However, if it did, reader-writer-locked code to do so might look as
>  follows (presumably, the field_count is only permitted to decrease,
> -otherwise, the added fields would need to be filled in):
> +otherwise, the added fields would need to be filled in)::
>  
>  	static inline int audit_upd_rule(struct audit_rule *rule,
>  					 struct list_head *list,
> @@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
>  The RCU version creates a copy, updates the copy, then replaces the old
>  entry with the newly updated entry.  This sequence of actions, allowing
>  concurrent reads while doing a copy to perform an update, is what gives
> -RCU ("read-copy update") its name.  The RCU code is as follows:
> +RCU ("read-copy update") its name.  The RCU code is as follows::
>  
>  	static inline int audit_upd_rule(struct audit_rule *rule,
>  					 struct list_head *list,
> @@ -216,8 +218,8 @@ RCU ("read-copy update") its name.  The RCU code is as follows:
>  Again, this assumes that the caller holds audit_netlink_sem.  Normally,
>  the reader-writer lock would become a spinlock in this sort of code.
>  
> -
>  Example 3: Eliminating Stale Data
> +---------------------------------
>  
>  The auditing examples above tolerate stale data, as do most algorithms
>  that are tracking external state.  Because there is a delay from the
> @@ -234,10 +236,12 @@ return holding the per-entry spinlock, as ipc_lock() does in fact do.
>  Quick Quiz:  Why does the search function need to return holding the
>  	per-entry lock for this deleted-flag technique to be helpful?
>  
> +:ref:`answer_quick_quiz`
> +
>  If the system-call audit module were to ever need to reject stale data,
>  one way to accomplish this would be to add a "deleted" flag and a "lock"
>  spinlock to the audit_entry structure, and modify audit_filter_task()
> -as follows:
> +as follows::
>  
>  	static enum audit_state audit_filter_task(struct task_struct *tsk)
>  	{
> @@ -268,7 +272,7 @@ audit_upd_rule() would need additional memory barriers to ensure
>  that the list_add_rcu() was really executed before the list_del_rcu().
>  
>  The audit_del_rule() function would need to set the "deleted"
> -flag under the spinlock as follows:
> +flag under the spinlock as follows::
>  
>  	static inline int audit_del_rule(struct audit_rule *rule,
>  					 struct list_head *list)
> @@ -290,8 +294,10 @@ flag under the spinlock as follows:
>  		return -EFAULT;		/* No matching rule */
>  	}
>  
> +.. _answer_quick_quiz:

Should the _answer_quick_quiz label below where 'Answer to Quick Quiz' is below?


>  
>  Summary
> +-------
>  
>  Read-mostly list-based data structures that can tolerate stale data are
>  the most amenable to use of RCU.  The simplest case is where entries are
> @@ -302,7 +308,6 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
>  in conjunction with a per-entry spinlock in order to allow the search
>  function to reject newly deleted data.
>  

That is, should it be here?

> -
>  Answer to Quick Quiz
>  	Why does the search function need to return holding the per-entry
>  	lock for this deleted-flag technique to be helpful?
> -- 
> 2.22.0
> 

thanks,

 - Joel

[Linux-kernel-mentees] [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST

[corbet]

On Sun, 23 Jun 2019 03:14:09 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/index.rst   |  1 +
>  Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++--------------
>  2 files changed, 20 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index bc8cd42a91cc..5a19c3642e88 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 1
>  
>     rcu
> +   list_rcu
>  
>  .. only:: subproject and html
>  
> diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
> index adb5a3782846..f786cd82c6a7 100644
> --- a/Documentation/RCU/listRCU.txt
> +++ b/Documentation/RCU/listRCU.txt
> @@ -1,14 +1,16 @@
> -Using RCU to Protect Read-Mostly Linked Lists
> +.. _list_rcu_doc:
>  
> +Using RCU to Protect Read-Mostly Linked Lists
> +=============================================
>  
>  One of the best applications of RCU is to protect read-mostly linked lists
> -("struct list_head" in list.h).  One big advantage of this approach
> +(*struct list_head* in ``list.h``).  One big advantage of this approach

Thanks for taking out the function markup from before; now I'll ask you to
take out this markup as well.  As a general rule, we try to use the minimal
amount of markup possible in our documentation in order to maximize the
readability of the .rst files.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST

[Jonathan Corbet]

On Sun, 23 Jun 2019 03:14:09 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/index.rst   |  1 +
>  Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++--------------
>  2 files changed, 20 insertions(+), 14 deletions(-)
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index bc8cd42a91cc..5a19c3642e88 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 1
>  
>     rcu
> +   list_rcu
>  
>  .. only:: subproject and html
>  
> diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/listRCU.txt
> index adb5a3782846..f786cd82c6a7 100644
> --- a/Documentation/RCU/listRCU.txt
> +++ b/Documentation/RCU/listRCU.txt
> @@ -1,14 +1,16 @@
> -Using RCU to Protect Read-Mostly Linked Lists
> +.. _list_rcu_doc:
>  
> +Using RCU to Protect Read-Mostly Linked Lists
> +=============================================
>  
>  One of the best applications of RCU is to protect read-mostly linked lists
> -("struct list_head" in list.h).  One big advantage of this approach
> +(*struct list_head* in ``list.h``).  One big advantage of this approach

Thanks for taking out the function markup from before; now I'll ask you to
take out this markup as well.  As a general rule, we try to use the minimal
amount of markup possible in our documentation in order to maximize the
readability of the .rst files.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST

[c0d1n61at3]

Rename RCU linked list txt file to rst.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{listRCU.txt => list_rcu.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (100%)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/list_rcu.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/list_rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST

[Jiunn Chang]

Rename RCU linked list txt file to rst.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{listRCU.txt => list_rcu.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (100%)

diff --git a/Documentation/RCU/listRCU.txt b/Documentation/RCU/list_rcu.rst
similarity index 100%
rename from Documentation/RCU/listRCU.txt
rename to Documentation/RCU/list_rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST

[c0d1n61at3]

ReST markup and TOC tree hook.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/UP.txt    | 27 ++++++++++++++-------------
 Documentation/RCU/index.rst |  1 +
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..10fede2acfc0 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,11 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
+Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in
 	this case?
 
-
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -78,23 +80,22 @@ or API changes would be required.
 
 Quick Quiz #2: What locking restriction must RCU callbacks respect?
 
-
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
 Quick Quiz #3: Why can't synchronize_rcu() return immediately on
 	UP systems running preemptable RCU?
 
-
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +120,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 5a19c3642e88..8349dd598bb8 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -9,6 +9,7 @@ RCU concepts
 
    rcu
    list_rcu
+   up_rcu
 
 .. only:: subproject and html
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST

[Jiunn Chang]

ReST markup and TOC tree hook.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/UP.txt    | 27 ++++++++++++++-------------
 Documentation/RCU/index.rst |  1 +
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
index 53bde717017b..10fede2acfc0 100644
--- a/Documentation/RCU/UP.txt
+++ b/Documentation/RCU/UP.txt
@@ -1,17 +1,19 @@
-RCU on Uniprocessor Systems
+.. _up_doc:
 
+RCU on Uniprocessor Systems
+===========================
 
 A common misconception is that, on UP systems, the call_rcu() primitive
 may immediately invoke its function.  The basis of this misconception
 is that since there is only one CPU, it should not be necessary to
 wait for anything else to get done, since there are no other CPUs for
-anything else to be happening on.  Although this approach will -sort- -of-
+anything else to be happening on.  Although this approach will *sort of*
 work a surprising amount of the time, it is a very bad idea in general.
 This document presents three examples that demonstrate exactly how bad
 an idea this is.
 
-
 Example 1: softirq Suicide
+--------------------------
 
 Suppose that an RCU-based algorithm scans a linked list containing
 elements A, B, and C in process context, and can delete elements from
@@ -28,8 +30,8 @@ your kernel.
 This same problem can occur if call_rcu() is invoked from a hardware
 interrupt handler.
 
-
 Example 2: Function-Call Fatality
+---------------------------------
 
 Of course, one could avert the suicide described in the preceding example
 by having call_rcu() directly invoke its arguments only if it was called
@@ -46,11 +48,11 @@ its arguments would cause it to fail to make the fundamental guarantee
 underlying RCU, namely that call_rcu() defers invoking its arguments until
 all RCU read-side critical sections currently executing have completed.
 
-Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
+Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in
 	this case?
 
-
 Example 3: Death by Deadlock
+----------------------------
 
 Suppose that call_rcu() is invoked while holding a lock, and that the
 callback function must acquire this same lock.  In this case, if
@@ -78,23 +80,22 @@ or API changes would be required.
 
 Quick Quiz #2: What locking restriction must RCU callbacks respect?
 
-
 Summary
+-------
 
 Permitting call_rcu() to immediately invoke its arguments breaks RCU,
 even on a UP system.  So do not do it!  Even on a UP system, the RCU
-infrastructure -must- respect grace periods, and -must- invoke callbacks
+infrastructure *must* respect grace periods, and *must* invoke callbacks
 from a known environment in which no locks are held.
 
-Note that it -is- safe for synchronize_rcu() to return immediately on
-UP systems, including !PREEMPT SMP builds running on UP systems.
+Note that it *is* safe for synchronize_rcu() to return immediately on
+UP systems, including PREEMPT SMP builds running on UP systems.
 
 Quick Quiz #3: Why can't synchronize_rcu() return immediately on
 	UP systems running preemptable RCU?
 
-
 Answer to Quick Quiz #1:
-	Why is it -not- legal to invoke synchronize_rcu() in this case?
+	Why is it *not* legal to invoke synchronize_rcu() in this case?
 
 	Because the calling function is scanning an RCU-protected linked
 	list, and is therefore within an RCU read-side critical section.
@@ -119,7 +120,7 @@ Answer to Quick Quiz #2:
 
 	This restriction might seem gratuitous, since very few RCU
 	callbacks acquire locks directly.  However, a great many RCU
-	callbacks do acquire locks -indirectly-, for example, via
+	callbacks do acquire locks *indirectly*, for example, via
 	the kfree() primitive.
 
 Answer to Quick Quiz #3:
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 5a19c3642e88..8349dd598bb8 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -9,6 +9,7 @@ RCU concepts
 
    rcu
    list_rcu
+   up_rcu
 
 .. only:: subproject and html
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST

[joel]

On Sun, Jun 23, 2019 at 03:14:11AM -0500, Jiunn Chang wrote:
> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/UP.txt    | 27 ++++++++++++++-------------
>  Documentation/RCU/index.rst |  1 +
>  2 files changed, 15 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..10fede2acfc0 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:
>  
> +RCU on Uniprocessor Systems
> +===========================
>  
>  A common misconception is that, on UP systems, the call_rcu() primitive
>  may immediately invoke its function.  The basis of this misconception
>  is that since there is only one CPU, it should not be necessary to
>  wait for anything else to get done, since there are no other CPUs for
> -anything else to be happening on.  Although this approach will -sort- -of-
> +anything else to be happening on.  Although this approach will *sort of*
>  work a surprising amount of the time, it is a very bad idea in general.
>  This document presents three examples that demonstrate exactly how bad
>  an idea this is.
>  
> -
>  Example 1: softirq Suicide
> +--------------------------
>  
>  Suppose that an RCU-based algorithm scans a linked list containing
>  elements A, B, and C in process context, and can delete elements from
> @@ -28,8 +30,8 @@ your kernel.
>  This same problem can occur if call_rcu() is invoked from a hardware
>  interrupt handler.
>  
> -
>  Example 2: Function-Call Fatality
> +---------------------------------
>  
>  Of course, one could avert the suicide described in the preceding example
>  by having call_rcu() directly invoke its arguments only if it was called
> @@ -46,11 +48,11 @@ its arguments would cause it to fail to make the fundamental guarantee
>  underlying RCU, namely that call_rcu() defers invoking its arguments until
>  all RCU read-side critical sections currently executing have completed.
>  
> -Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
> +Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in

To keep it consistent - here you can link to the quick quiz answers as well,
like you did for list_rcu.rst

Other than that it looks fine to me.

Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>

thanks,

 - Joel


>  	this case?
>  
> -
>  Example 3: Death by Deadlock
> +----------------------------
>  
>  Suppose that call_rcu() is invoked while holding a lock, and that the
>  callback function must acquire this same lock.  In this case, if
> @@ -78,23 +80,22 @@ or API changes would be required.
>  
>  Quick Quiz #2: What locking restriction must RCU callbacks respect?
>  
> -
>  Summary
> +-------
>  
>  Permitting call_rcu() to immediately invoke its arguments breaks RCU,
>  even on a UP system.  So do not do it!  Even on a UP system, the RCU
> -infrastructure -must- respect grace periods, and -must- invoke callbacks
> +infrastructure *must* respect grace periods, and *must* invoke callbacks
>  from a known environment in which no locks are held.
>  
> -Note that it -is- safe for synchronize_rcu() to return immediately on
> -UP systems, including !PREEMPT SMP builds running on UP systems.
> +Note that it *is* safe for synchronize_rcu() to return immediately on
> +UP systems, including PREEMPT SMP builds running on UP systems.
>  
>  Quick Quiz #3: Why can't synchronize_rcu() return immediately on
>  	UP systems running preemptable RCU?
>  
> -
>  Answer to Quick Quiz #1:
> -	Why is it -not- legal to invoke synchronize_rcu() in this case?
> +	Why is it *not* legal to invoke synchronize_rcu() in this case?
>  
>  	Because the calling function is scanning an RCU-protected linked
>  	list, and is therefore within an RCU read-side critical section.
> @@ -119,7 +120,7 @@ Answer to Quick Quiz #2:
>  
>  	This restriction might seem gratuitous, since very few RCU
>  	callbacks acquire locks directly.  However, a great many RCU
> -	callbacks do acquire locks -indirectly-, for example, via
> +	callbacks do acquire locks *indirectly*, for example, via
>  	the kfree() primitive.
>  
>  Answer to Quick Quiz #3:
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index 5a19c3642e88..8349dd598bb8 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -9,6 +9,7 @@ RCU concepts
>  
>     rcu
>     list_rcu
> +   up_rcu
>  
>  .. only:: subproject and html
>  
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST

[Joel Fernandes]

On Sun, Jun 23, 2019 at 03:14:11AM -0500, Jiunn Chang wrote:
> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/UP.txt    | 27 ++++++++++++++-------------
>  Documentation/RCU/index.rst |  1 +
>  2 files changed, 15 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..10fede2acfc0 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:
>  
> +RCU on Uniprocessor Systems
> +===========================
>  
>  A common misconception is that, on UP systems, the call_rcu() primitive
>  may immediately invoke its function.  The basis of this misconception
>  is that since there is only one CPU, it should not be necessary to
>  wait for anything else to get done, since there are no other CPUs for
> -anything else to be happening on.  Although this approach will -sort- -of-
> +anything else to be happening on.  Although this approach will *sort of*
>  work a surprising amount of the time, it is a very bad idea in general.
>  This document presents three examples that demonstrate exactly how bad
>  an idea this is.
>  
> -
>  Example 1: softirq Suicide
> +--------------------------
>  
>  Suppose that an RCU-based algorithm scans a linked list containing
>  elements A, B, and C in process context, and can delete elements from
> @@ -28,8 +30,8 @@ your kernel.
>  This same problem can occur if call_rcu() is invoked from a hardware
>  interrupt handler.
>  
> -
>  Example 2: Function-Call Fatality
> +---------------------------------
>  
>  Of course, one could avert the suicide described in the preceding example
>  by having call_rcu() directly invoke its arguments only if it was called
> @@ -46,11 +48,11 @@ its arguments would cause it to fail to make the fundamental guarantee
>  underlying RCU, namely that call_rcu() defers invoking its arguments until
>  all RCU read-side critical sections currently executing have completed.
>  
> -Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
> +Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in

To keep it consistent - here you can link to the quick quiz answers as well,
like you did for list_rcu.rst

Other than that it looks fine to me.

Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>

thanks,

 - Joel


>  	this case?
>  
> -
>  Example 3: Death by Deadlock
> +----------------------------
>  
>  Suppose that call_rcu() is invoked while holding a lock, and that the
>  callback function must acquire this same lock.  In this case, if
> @@ -78,23 +80,22 @@ or API changes would be required.
>  
>  Quick Quiz #2: What locking restriction must RCU callbacks respect?
>  
> -
>  Summary
> +-------
>  
>  Permitting call_rcu() to immediately invoke its arguments breaks RCU,
>  even on a UP system.  So do not do it!  Even on a UP system, the RCU
> -infrastructure -must- respect grace periods, and -must- invoke callbacks
> +infrastructure *must* respect grace periods, and *must* invoke callbacks
>  from a known environment in which no locks are held.
>  
> -Note that it -is- safe for synchronize_rcu() to return immediately on
> -UP systems, including !PREEMPT SMP builds running on UP systems.
> +Note that it *is* safe for synchronize_rcu() to return immediately on
> +UP systems, including PREEMPT SMP builds running on UP systems.
>  
>  Quick Quiz #3: Why can't synchronize_rcu() return immediately on
>  	UP systems running preemptable RCU?
>  
> -
>  Answer to Quick Quiz #1:
> -	Why is it -not- legal to invoke synchronize_rcu() in this case?
> +	Why is it *not* legal to invoke synchronize_rcu() in this case?
>  
>  	Because the calling function is scanning an RCU-protected linked
>  	list, and is therefore within an RCU read-side critical section.
> @@ -119,7 +120,7 @@ Answer to Quick Quiz #2:
>  
>  	This restriction might seem gratuitous, since very few RCU
>  	callbacks acquire locks directly.  However, a great many RCU
> -	callbacks do acquire locks -indirectly-, for example, via
> +	callbacks do acquire locks *indirectly*, for example, via
>  	the kfree() primitive.
>  
>  Answer to Quick Quiz #3:
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index 5a19c3642e88..8349dd598bb8 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -9,6 +9,7 @@ RCU concepts
>  
>     rcu
>     list_rcu
> +   up_rcu
>  
>  .. only:: subproject and html
>  
> -- 
> 2.22.0
> 

[Linux-kernel-mentees] [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST

[corbet]

On Sun, 23 Jun 2019 03:14:11 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/UP.txt    | 27 ++++++++++++++-------------
>  Documentation/RCU/index.rst |  1 +
>  2 files changed, 15 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..10fede2acfc0 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:
>  
> +RCU on Uniprocessor Systems
> +===========================
>  
>  A common misconception is that, on UP systems, the call_rcu() primitive
>  may immediately invoke its function.  The basis of this misconception
>  is that since there is only one CPU, it should not be necessary to
>  wait for anything else to get done, since there are no other CPUs for
> -anything else to be happening on.  Although this approach will -sort- -of-
> +anything else to be happening on.  Although this approach will *sort of*

Just in case you're wondering, this markup is fine; it's an actual emphasis
that you're preserving from the original.

>  work a surprising amount of the time, it is a very bad idea in general.
>  This document presents three examples that demonstrate exactly how bad
>  an idea this is.
>  
> -
>  Example 1: softirq Suicide
> +--------------------------
>  
>  Suppose that an RCU-based algorithm scans a linked list containing
>  elements A, B, and C in process context, and can delete elements from
> @@ -28,8 +30,8 @@ your kernel.
>  This same problem can occur if call_rcu() is invoked from a hardware
>  interrupt handler.
>  
> -
>  Example 2: Function-Call Fatality
> +---------------------------------
>  
>  Of course, one could avert the suicide described in the preceding example
>  by having call_rcu() directly invoke its arguments only if it was called
> @@ -46,11 +48,11 @@ its arguments would cause it to fail to make the fundamental guarantee
>  underlying RCU, namely that call_rcu() defers invoking its arguments until
>  all RCU read-side critical sections currently executing have completed.
>  
> -Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
> +Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in
>  	this case?

Have you actually built the docs with these changes and looked at the
results?  This will not render the way you might like.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST

[Jonathan Corbet]

On Sun, 23 Jun 2019 03:14:11 -0500
Jiunn Chang <c0d1n61at3 at gmail.com> wrote:

> ReST markup and TOC tree hook.
> 
> Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
> ---
>  Documentation/RCU/UP.txt    | 27 ++++++++++++++-------------
>  Documentation/RCU/index.rst |  1 +
>  2 files changed, 15 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> index 53bde717017b..10fede2acfc0 100644
> --- a/Documentation/RCU/UP.txt
> +++ b/Documentation/RCU/UP.txt
> @@ -1,17 +1,19 @@
> -RCU on Uniprocessor Systems
> +.. _up_doc:
>  
> +RCU on Uniprocessor Systems
> +===========================
>  
>  A common misconception is that, on UP systems, the call_rcu() primitive
>  may immediately invoke its function.  The basis of this misconception
>  is that since there is only one CPU, it should not be necessary to
>  wait for anything else to get done, since there are no other CPUs for
> -anything else to be happening on.  Although this approach will -sort- -of-
> +anything else to be happening on.  Although this approach will *sort of*

Just in case you're wondering, this markup is fine; it's an actual emphasis
that you're preserving from the original.

>  work a surprising amount of the time, it is a very bad idea in general.
>  This document presents three examples that demonstrate exactly how bad
>  an idea this is.
>  
> -
>  Example 1: softirq Suicide
> +--------------------------
>  
>  Suppose that an RCU-based algorithm scans a linked list containing
>  elements A, B, and C in process context, and can delete elements from
> @@ -28,8 +30,8 @@ your kernel.
>  This same problem can occur if call_rcu() is invoked from a hardware
>  interrupt handler.
>  
> -
>  Example 2: Function-Call Fatality
> +---------------------------------
>  
>  Of course, one could avert the suicide described in the preceding example
>  by having call_rcu() directly invoke its arguments only if it was called
> @@ -46,11 +48,11 @@ its arguments would cause it to fail to make the fundamental guarantee
>  underlying RCU, namely that call_rcu() defers invoking its arguments until
>  all RCU read-side critical sections currently executing have completed.
>  
> -Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
> +Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in
>  	this case?

Have you actually built the docs with these changes and looked at the
results?  This will not render the way you might like.

Thanks,

jon

[Linux-kernel-mentees] [PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST

[c0d1n61at3]

Rename RCU UP systems txt file to rst.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{UP.txt => up_rcu.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (100%)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/up_rcu.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/up_rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST

[Jiunn Chang]

Rename RCU UP systems txt file to rst.

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/{UP.txt => up_rcu.rst} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/RCU/{UP.txt => up_rcu.rst} (100%)

diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/up_rcu.rst
similarity index 100%
rename from Documentation/RCU/UP.txt
rename to Documentation/RCU/up_rcu.rst
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 7/7] Documentation: RCU: Add links to rcu.rst

[c0d1n61at3]

Add the following links to rcu.rst:
	list_rcu
	up_rcu

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/rcu.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 2b93b128a6fd..3d21ebf66daa 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -11,8 +11,8 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
+a grace period to elapse, then free the element.  See :ref:`list_rcu`
+for more information on using RCU with linked lists.
 
 Frequently Asked Questions
 
@@ -49,7 +49,7 @@ Frequently Asked Questions
 - If I am running on a uniprocessor kernel, which can only do one
   thing at a time, why should I wait for a grace period?
 
-  See the UP.txt file in this directory.
+  See :ref:`up_rcu` for more information.
 
 - How can I see where RCU is currently used in the Linux kernel?
 
@@ -67,7 +67,7 @@ Frequently Asked Questions
 
 - Why the name "RCU"?
 
-  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  "RCU" stands for "read-copy update".  :ref:`list_rcu` has
   more information on where this name came from, search for
   "read-copy update" to find it.
 
-- 
2.22.0

[Linux-kernel-mentees] [PATCH v2 7/7] Documentation: RCU: Add links to rcu.rst

[Jiunn Chang]

Add the following links to rcu.rst:
	list_rcu
	up_rcu

Signed-off-by: Jiunn Chang <c0d1n61at3 at gmail.com>
---
 Documentation/RCU/rcu.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 2b93b128a6fd..3d21ebf66daa 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -11,8 +11,8 @@ A "grace period" must elapse between the two parts, and this grace period
 must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
-a grace period to elapse, then free the element.  See the listRCU.txt
-file for more information on using RCU with linked lists.
+a grace period to elapse, then free the element.  See :ref:`list_rcu`
+for more information on using RCU with linked lists.
 
 Frequently Asked Questions
 
@@ -49,7 +49,7 @@ Frequently Asked Questions
 - If I am running on a uniprocessor kernel, which can only do one
   thing at a time, why should I wait for a grace period?
 
-  See the UP.txt file in this directory.
+  See :ref:`up_rcu` for more information.
 
 - How can I see where RCU is currently used in the Linux kernel?
 
@@ -67,7 +67,7 @@ Frequently Asked Questions
 
 - Why the name "RCU"?
 
-  "RCU" stands for "read-copy update".  The file listRCU.txt has
+  "RCU" stands for "read-copy update".  :ref:`list_rcu` has
   more information on where this name came from, search for
   "read-copy update" to find it.
 
-- 
2.22.0