Linux Kernel Mentees Archive on lore.kernel.org
 help / color / Atom feed
* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
@ 2019-10-30 23:31 tranmanphong at gmail.com (Phong Tran)
  2019-10-30 23:31 ` tranmanphong
                   ` (2 more replies)
  0 siblings, 3 replies; 23+ messages in thread
From: tranmanphong at gmail.com (Phong Tran) @ 2019-10-30 23:31 UTC (permalink / raw)


Sync the format with current state of kernel documentation.
This change base on rcu-dev branch
what changed:
- Format bullet lists
- Add literal blocks

Signed-off-by: Phong Tran <tranmanphong at gmail.com>
---
 Documentation/RCU/index.rst                   |   1 +
 .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
 2 files changed, 90 insertions(+), 61 deletions(-)
 rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 627128c230dc..b9b11481c727 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -8,6 +8,7 @@ RCU concepts
    :maxdepth: 3
 
    arrayRCU
+   whatisRCU
    rcu
    listRCU
    NMI-RCU
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst
similarity index 91%
rename from Documentation/RCU/whatisRCU.txt
rename to Documentation/RCU/whatisRCU.rst
index 58ba05c4d97f..70d0e4c21917 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.rst
@@ -1,15 +1,18 @@
+.. _rcu_doc:
+
 What is RCU?  --  "Read, Copy, Update"
+======================================
 
 Please note that the "What is RCU?" LWN series is an excellent place
 to start learning about RCU:
 
-1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
-2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
-3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
-4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
-	2010 Big API Table           http://lwn.net/Articles/419086/
-5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
-	2014 Big API Table           http://lwn.net/Articles/609973/
+| 1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
+| 2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
+| 3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
+| 4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
+| 	2010 Big API Table           http://lwn.net/Articles/419086/
+| 5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
+|	2014 Big API Table           http://lwn.net/Articles/609973/
 
 
 What is RCU?
@@ -51,6 +54,7 @@ never need this document anyway.  ;-)
 
 
 1.  RCU OVERVIEW
+----------------
 
 The basic idea behind RCU is to split updates into "removal" and
 "reclamation" phases.  The removal phase removes references to data items
@@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
 
 
 2.  WHAT IS RCU'S CORE API?
+---------------------------
 
 The core RCU API is quite small:
 
@@ -166,7 +171,7 @@ synchronize_rcu()
 	read-side critical sections on all CPUs have completed.
 	Note that synchronize_rcu() will -not- necessarily wait for
 	any subsequent RCU read-side critical sections to complete.
-	For example, consider the following sequence of events:
+	For example, consider the following sequence of events::
 
 	         CPU 0                  CPU 1                 CPU 2
 	     ----------------- ------------------------- ---------------
@@ -248,13 +253,13 @@ rcu_dereference()
 
 	Common coding practice uses rcu_dereference() to copy an
 	RCU-protected pointer to a local variable, then dereferences
-	this local variable, for example as follows:
+	this local variable, for example as follows::
 
 		p = rcu_dereference(head.next);
 		return p->data;
 
 	However, in this case, one could just as easily combine these
-	into one statement:
+	into one statement::
 
 		return rcu_dereference(head.next)->data;
 
@@ -267,7 +272,7 @@ rcu_dereference()
 
 	Note that the value returned by rcu_dereference() is valid
 	only within the enclosing RCU read-side critical section [1].
-	For example, the following is -not- legal:
+	For example, the following is -not- legal::
 
 		rcu_read_lock();
 		p = rcu_dereference(head.next);
@@ -315,6 +320,7 @@ rcu_dereference()
 
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.
+::
 
 
 	    rcu_assign_pointer()
@@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
 
 
 3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
+-----------------------------------------------
 
 This section shows a simple use of the core RCU API to protect a
 global pointer to a dynamically allocated structure.  More-typical
 uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
+::
 
 	struct foo {
 		int a;
@@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
 
 
 4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
+--------------------------------------------
 
 In the example above, foo_update_a() blocks until a grace period elapses.
 This is quite simple, but in some cases one cannot afford to wait so
 long -- there might be other high-priority work to be done.
 
 In such cases, one uses call_rcu() rather than synchronize_rcu().
-The call_rcu() API is as follows:
+The call_rcu() API is as follows::
 
 	void call_rcu(struct rcu_head * head,
 		      void (*func)(struct rcu_head *head));
@@ -481,7 +490,7 @@ The call_rcu() API is as follows:
 This function invokes func(head) after a grace period has elapsed.
 This invocation might happen from either softirq or process context,
 so the function is not permitted to block.  The foo struct needs to
-have an rcu_head structure added, perhaps as follows:
+have an rcu_head structure added, perhaps as follows::
 
 	struct foo {
 		int a;
@@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
 		struct rcu_head rcu;
 	};
 
-The foo_update_a() function might then be written as follows:
+The foo_update_a() function might then be written as follows::
 
 	/*
 	 * Create a new struct foo that is the same as the one currently
@@ -520,7 +529,7 @@ The foo_update_a() function might then be written as follows:
 		call_rcu(&old_fp->rcu, foo_reclaim);
 	}
 
-The foo_reclaim() function might appear as follows:
+The foo_reclaim() function might appear as follows::
 
 	void foo_reclaim(struct rcu_head *rp)
 	{
@@ -552,7 +561,7 @@ o	Use call_rcu() -after- removing a data element from an
 
 If the callback for call_rcu() is not doing anything more than calling
 kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
-to avoid having to write your own callback:
+to avoid having to write your own callback::
 
 	kfree_rcu(old_fp, rcu);
 
@@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules governing the use of RCU.
 
 
 5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
+------------------------------------------------
 
 One of the nice things about RCU is that it has extremely simple "toy"
 implementations that are a good first step towards understanding the
@@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can deadlock.
 However, it is probably the easiest implementation to relate to, so is
 a good starting point.
 
-It is extremely simple:
+It is extremely simple::
 
 	static DEFINE_RWLOCK(rcu_gp_mutex);
 
@@ -614,7 +624,7 @@ It is extremely simple:
 
 [You can ignore rcu_assign_pointer() and rcu_dereference() without missing
 much.  But here are simplified versions anyway.  And whatever you do,
-don't forget about them when submitting patches making use of RCU!]
+don't forget about them when submitting patches making use of RCU!]::
 
 	#define rcu_assign_pointer(p, v) \
 	({ \
@@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that is based on
 on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
 kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
 are the same as those shown in the preceding section, so they are omitted.
+::
 
 	void rcu_read_lock(void) { }
 
@@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU read-side
 
 
 6.  ANALOGY WITH READER-WRITER LOCKING
+--------------------------------------
 
 Although RCU can be used in many different ways, a very common use of
 RCU is analogous to reader-writer locking.  The following unified
 diff shows how closely related RCU and reader-writer locking can be.
+::
 
 	@@ -5,5 +5,5 @@ struct el {
 	 	int data;
@@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer locking can be.
 		return 0;
 	 }
 
-Or, for those who prefer a side-by-side listing:
+Or, for those who prefer a side-by-side listing::
 
  1 struct el {                          1 struct el {
  2   struct list_head list;             2   struct list_head list;
@@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
  8 rwlock_t listmutex;                  8 spinlock_t listmutex;
  9 struct el head;                      9 struct el head;
 
- 1 int search(long key, int *result)    1 int search(long key, int *result)
- 2 {                                    2 {
- 3   struct list_head *lp;              3   struct list_head *lp;
- 4   struct el *p;                      4   struct el *p;
- 5                                      5
- 6   read_lock(&listmutex);             6   rcu_read_lock();
- 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
- 8     if (p->key == key) {             8     if (p->key == key) {
- 9       *result = p->data;             9       *result = p->data;
-10       read_unlock(&listmutex);      10       rcu_read_unlock();
-11       return 1;                     11       return 1;
-12     }                               12     }
-13   }                                 13   }
-14   read_unlock(&listmutex);          14   rcu_read_unlock();
-15   return 0;                         15   return 0;
-16 }                                   16 }
-
- 1 int delete(long key)                 1 int delete(long key)
- 2 {                                    2 {
- 3   struct el *p;                      3   struct el *p;
- 4                                      4
- 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
- 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
- 7     if (p->key == key) {             7     if (p->key == key) {
- 8       list_del(&p->list);            8       list_del_rcu(&p->list);
- 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
-                                       10       synchronize_rcu();
-10       kfree(p);                     11       kfree(p);
-11       return 1;                     12       return 1;
-12     }                               13     }
-13   }                                 14   }
-14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
-15   return 0;                         16   return 0;
-16 }                                   17 }
+::
+
+  1 int search(long key, int *result)    1 int search(long key, int *result)
+  2 {                                    2 {
+  3   struct list_head *lp;              3   struct list_head *lp;
+  4   struct el *p;                      4   struct el *p;
+  5                                      5
+  6   read_lock(&listmutex);             6   rcu_read_lock();
+  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
+  8     if (p->key == key) {             8     if (p->key == key) {
+  9       *result = p->data;             9       *result = p->data;
+ 10       read_unlock(&listmutex);      10       rcu_read_unlock();
+ 11       return 1;                     11       return 1;
+ 12     }                               12     }
+ 13   }                                 13   }
+ 14   read_unlock(&listmutex);          14   rcu_read_unlock();
+ 15   return 0;                         15   return 0;
+ 16 }                                   16 }
+
+::
+
+  1 int delete(long key)                 1 int delete(long key)
+  2 {                                    2 {
+  3   struct el *p;                      3   struct el *p;
+  4                                      4
+  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
+  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
+  7     if (p->key == key) {             7     if (p->key == key) {
+  8       list_del(&p->list);            8       list_del_rcu(&p->list);
+  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
+                                        10       synchronize_rcu();
+ 10       kfree(p);                     11       kfree(p);
+ 11       return 1;                     12       return 1;
+ 12     }                               13     }
+ 13   }                                 14   }
+ 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
+ 15   return 0;                         16   return 0;
+ 16 }                                   17 }
 
 Either way, the differences are quite small.  Read-side locking moves
 to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
@@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
 
 
 7.  FULL LIST OF RCU APIs
+-------------------------
 
 The RCU APIs are documented in docbook-format header comments in the
 Linux-kernel source code, but it helps to have a full list of the
 APIs, since there does not appear to be a way to categorize them
 in docbook.  Here is the list, by category.
 
-RCU list traversal:
+RCU list traversal::
 
 	list_entry_rcu
 	list_first_entry_rcu
@@ -854,7 +872,7 @@ RCU list traversal:
 	hlist_bl_first_rcu
 	hlist_bl_for_each_entry_rcu
 
-RCU pointer/list update:
+RCU pointer/list udate::
 
 	rcu_assign_pointer
 	list_add_rcu
@@ -876,7 +894,9 @@ RCU pointer/list update:
 	hlist_bl_del_rcu
 	hlist_bl_set_first_rcu
 
-RCU:	Critical sections	Grace period		Barrier
+RCU::
+
+	Critical sections	Grace period		Barrier
 
 	rcu_read_lock		synchronize_net		rcu_barrier
 	rcu_read_unlock		synchronize_rcu
@@ -885,7 +905,9 @@ RCU:	Critical sections	Grace period		Barrier
 	rcu_dereference_check	kfree_rcu
 	rcu_dereference_protected
 
-bh:	Critical sections	Grace period		Barrier
+bh::
+
+	Critical sections	Grace period		Barrier
 
 	rcu_read_lock_bh	call_rcu		rcu_barrier
 	rcu_read_unlock_bh	synchronize_rcu
@@ -896,7 +918,9 @@ bh:	Critical sections	Grace period		Barrier
 	rcu_dereference_bh_protected
 	rcu_read_lock_bh_held
 
-sched:	Critical sections	Grace period		Barrier
+sched::
+
+	Critical sections	Grace period		Barrier
 
 	rcu_read_lock_sched	call_rcu		rcu_barrier
 	rcu_read_unlock_sched	synchronize_rcu
@@ -910,7 +934,9 @@ sched:	Critical sections	Grace period		Barrier
 	rcu_read_lock_sched_held
 
 
-SRCU:	Critical sections	Grace period		Barrier
+SRCU::
+
+	Critical sections	Grace period		Barrier
 
 	srcu_read_lock		call_srcu		srcu_barrier
 	srcu_read_unlock	synchronize_srcu
@@ -918,13 +944,14 @@ SRCU:	Critical sections	Grace period		Barrier
 	srcu_dereference_check
 	srcu_read_lock_held
 
-SRCU:	Initialization/cleanup
+SRCU: Initialization/cleanup::
+
 	DEFINE_SRCU
 	DEFINE_STATIC_SRCU
 	init_srcu_struct
 	cleanup_srcu_struct
 
-All:  lockdep-checked RCU-protected pointer access
+All: lockdep-checked RCU-protected pointer access::
 
 	rcu_access_pointer
 	rcu_dereference_raw
@@ -976,6 +1003,7 @@ the right tool for your job.
 
 
 8.  ANSWERS TO QUICK QUIZZES
+----------------------------
 
 Quick Quiz #1:	Why is this argument naive?  How could a deadlock
 		occur when using this algorithm in a real-world Linux
-- 
2.20.1

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-10-30 23:31 [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst tranmanphong at gmail.com (Phong Tran)
@ 2019-10-30 23:31 ` tranmanphong
  2019-10-31 22:54 ` paulmck at kernel.org (Paul E. McKenney)
  2019-11-02  8:31 ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  2 siblings, 0 replies; 23+ messages in thread
From: tranmanphong @ 2019-10-30 23:31 UTC (permalink / raw)


Sync the format with current state of kernel documentation.
This change base on rcu-dev branch
what changed:
- Format bullet lists
- Add literal blocks

Signed-off-by: Phong Tran <tranmanphong at gmail.com>
---
 Documentation/RCU/index.rst                   |   1 +
 .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
 2 files changed, 90 insertions(+), 61 deletions(-)
 rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)

diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
index 627128c230dc..b9b11481c727 100644
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -8,6 +8,7 @@ RCU concepts
    :maxdepth: 3
 
    arrayRCU
+   whatisRCU
    rcu
    listRCU
    NMI-RCU
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst
similarity index 91%
rename from Documentation/RCU/whatisRCU.txt
rename to Documentation/RCU/whatisRCU.rst
index 58ba05c4d97f..70d0e4c21917 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.rst
@@ -1,15 +1,18 @@
+.. _rcu_doc:
+
 What is RCU?  --  "Read, Copy, Update"
+======================================
 
 Please note that the "What is RCU?" LWN series is an excellent place
 to start learning about RCU:
 
-1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
-2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
-3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
-4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
-	2010 Big API Table           http://lwn.net/Articles/419086/
-5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
-	2014 Big API Table           http://lwn.net/Articles/609973/
+| 1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
+| 2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
+| 3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
+| 4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
+| 	2010 Big API Table           http://lwn.net/Articles/419086/
+| 5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
+|	2014 Big API Table           http://lwn.net/Articles/609973/
 
 
 What is RCU?
@@ -51,6 +54,7 @@ never need this document anyway.  ;-)
 
 
 1.  RCU OVERVIEW
+----------------
 
 The basic idea behind RCU is to split updates into "removal" and
 "reclamation" phases.  The removal phase removes references to data items
@@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
 
 
 2.  WHAT IS RCU'S CORE API?
+---------------------------
 
 The core RCU API is quite small:
 
@@ -166,7 +171,7 @@ synchronize_rcu()
 	read-side critical sections on all CPUs have completed.
 	Note that synchronize_rcu() will -not- necessarily wait for
 	any subsequent RCU read-side critical sections to complete.
-	For example, consider the following sequence of events:
+	For example, consider the following sequence of events::
 
 	         CPU 0                  CPU 1                 CPU 2
 	     ----------------- ------------------------- ---------------
@@ -248,13 +253,13 @@ rcu_dereference()
 
 	Common coding practice uses rcu_dereference() to copy an
 	RCU-protected pointer to a local variable, then dereferences
-	this local variable, for example as follows:
+	this local variable, for example as follows::
 
 		p = rcu_dereference(head.next);
 		return p->data;
 
 	However, in this case, one could just as easily combine these
-	into one statement:
+	into one statement::
 
 		return rcu_dereference(head.next)->data;
 
@@ -267,7 +272,7 @@ rcu_dereference()
 
 	Note that the value returned by rcu_dereference() is valid
 	only within the enclosing RCU read-side critical section [1].
-	For example, the following is -not- legal:
+	For example, the following is -not- legal::
 
 		rcu_read_lock();
 		p = rcu_dereference(head.next);
@@ -315,6 +320,7 @@ rcu_dereference()
 
 The following diagram shows how each API communicates among the
 reader, updater, and reclaimer.
+::
 
 
 	    rcu_assign_pointer()
@@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
 
 
 3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
+-----------------------------------------------
 
 This section shows a simple use of the core RCU API to protect a
 global pointer to a dynamically allocated structure.  More-typical
 uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
+::
 
 	struct foo {
 		int a;
@@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
 
 
 4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
+--------------------------------------------
 
 In the example above, foo_update_a() blocks until a grace period elapses.
 This is quite simple, but in some cases one cannot afford to wait so
 long -- there might be other high-priority work to be done.
 
 In such cases, one uses call_rcu() rather than synchronize_rcu().
-The call_rcu() API is as follows:
+The call_rcu() API is as follows::
 
 	void call_rcu(struct rcu_head * head,
 		      void (*func)(struct rcu_head *head));
@@ -481,7 +490,7 @@ The call_rcu() API is as follows:
 This function invokes func(head) after a grace period has elapsed.
 This invocation might happen from either softirq or process context,
 so the function is not permitted to block.  The foo struct needs to
-have an rcu_head structure added, perhaps as follows:
+have an rcu_head structure added, perhaps as follows::
 
 	struct foo {
 		int a;
@@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
 		struct rcu_head rcu;
 	};
 
-The foo_update_a() function might then be written as follows:
+The foo_update_a() function might then be written as follows::
 
 	/*
 	 * Create a new struct foo that is the same as the one currently
@@ -520,7 +529,7 @@ The foo_update_a() function might then be written as follows:
 		call_rcu(&old_fp->rcu, foo_reclaim);
 	}
 
-The foo_reclaim() function might appear as follows:
+The foo_reclaim() function might appear as follows::
 
 	void foo_reclaim(struct rcu_head *rp)
 	{
@@ -552,7 +561,7 @@ o	Use call_rcu() -after- removing a data element from an
 
 If the callback for call_rcu() is not doing anything more than calling
 kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
-to avoid having to write your own callback:
+to avoid having to write your own callback::
 
 	kfree_rcu(old_fp, rcu);
 
@@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules governing the use of RCU.
 
 
 5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
+------------------------------------------------
 
 One of the nice things about RCU is that it has extremely simple "toy"
 implementations that are a good first step towards understanding the
@@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can deadlock.
 However, it is probably the easiest implementation to relate to, so is
 a good starting point.
 
-It is extremely simple:
+It is extremely simple::
 
 	static DEFINE_RWLOCK(rcu_gp_mutex);
 
@@ -614,7 +624,7 @@ It is extremely simple:
 
 [You can ignore rcu_assign_pointer() and rcu_dereference() without missing
 much.  But here are simplified versions anyway.  And whatever you do,
-don't forget about them when submitting patches making use of RCU!]
+don't forget about them when submitting patches making use of RCU!]::
 
 	#define rcu_assign_pointer(p, v) \
 	({ \
@@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that is based on
 on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
 kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
 are the same as those shown in the preceding section, so they are omitted.
+::
 
 	void rcu_read_lock(void) { }
 
@@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU read-side
 
 
 6.  ANALOGY WITH READER-WRITER LOCKING
+--------------------------------------
 
 Although RCU can be used in many different ways, a very common use of
 RCU is analogous to reader-writer locking.  The following unified
 diff shows how closely related RCU and reader-writer locking can be.
+::
 
 	@@ -5,5 +5,5 @@ struct el {
 	 	int data;
@@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer locking can be.
 		return 0;
 	 }
 
-Or, for those who prefer a side-by-side listing:
+Or, for those who prefer a side-by-side listing::
 
  1 struct el {                          1 struct el {
  2   struct list_head list;             2   struct list_head list;
@@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
  8 rwlock_t listmutex;                  8 spinlock_t listmutex;
  9 struct el head;                      9 struct el head;
 
- 1 int search(long key, int *result)    1 int search(long key, int *result)
- 2 {                                    2 {
- 3   struct list_head *lp;              3   struct list_head *lp;
- 4   struct el *p;                      4   struct el *p;
- 5                                      5
- 6   read_lock(&listmutex);             6   rcu_read_lock();
- 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
- 8     if (p->key == key) {             8     if (p->key == key) {
- 9       *result = p->data;             9       *result = p->data;
-10       read_unlock(&listmutex);      10       rcu_read_unlock();
-11       return 1;                     11       return 1;
-12     }                               12     }
-13   }                                 13   }
-14   read_unlock(&listmutex);          14   rcu_read_unlock();
-15   return 0;                         15   return 0;
-16 }                                   16 }
-
- 1 int delete(long key)                 1 int delete(long key)
- 2 {                                    2 {
- 3   struct el *p;                      3   struct el *p;
- 4                                      4
- 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
- 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
- 7     if (p->key == key) {             7     if (p->key == key) {
- 8       list_del(&p->list);            8       list_del_rcu(&p->list);
- 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
-                                       10       synchronize_rcu();
-10       kfree(p);                     11       kfree(p);
-11       return 1;                     12       return 1;
-12     }                               13     }
-13   }                                 14   }
-14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
-15   return 0;                         16   return 0;
-16 }                                   17 }
+::
+
+  1 int search(long key, int *result)    1 int search(long key, int *result)
+  2 {                                    2 {
+  3   struct list_head *lp;              3   struct list_head *lp;
+  4   struct el *p;                      4   struct el *p;
+  5                                      5
+  6   read_lock(&listmutex);             6   rcu_read_lock();
+  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
+  8     if (p->key == key) {             8     if (p->key == key) {
+  9       *result = p->data;             9       *result = p->data;
+ 10       read_unlock(&listmutex);      10       rcu_read_unlock();
+ 11       return 1;                     11       return 1;
+ 12     }                               12     }
+ 13   }                                 13   }
+ 14   read_unlock(&listmutex);          14   rcu_read_unlock();
+ 15   return 0;                         15   return 0;
+ 16 }                                   16 }
+
+::
+
+  1 int delete(long key)                 1 int delete(long key)
+  2 {                                    2 {
+  3   struct el *p;                      3   struct el *p;
+  4                                      4
+  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
+  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
+  7     if (p->key == key) {             7     if (p->key == key) {
+  8       list_del(&p->list);            8       list_del_rcu(&p->list);
+  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
+                                        10       synchronize_rcu();
+ 10       kfree(p);                     11       kfree(p);
+ 11       return 1;                     12       return 1;
+ 12     }                               13     }
+ 13   }                                 14   }
+ 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
+ 15   return 0;                         16   return 0;
+ 16 }                                   17 }
 
 Either way, the differences are quite small.  Read-side locking moves
 to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
@@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
 
 
 7.  FULL LIST OF RCU APIs
+-------------------------
 
 The RCU APIs are documented in docbook-format header comments in the
 Linux-kernel source code, but it helps to have a full list of the
 APIs, since there does not appear to be a way to categorize them
 in docbook.  Here is the list, by category.
 
-RCU list traversal:
+RCU list traversal::
 
 	list_entry_rcu
 	list_first_entry_rcu
@@ -854,7 +872,7 @@ RCU list traversal:
 	hlist_bl_first_rcu
 	hlist_bl_for_each_entry_rcu
 
-RCU pointer/list update:
+RCU pointer/list udate::
 
 	rcu_assign_pointer
 	list_add_rcu
@@ -876,7 +894,9 @@ RCU pointer/list update:
 	hlist_bl_del_rcu
 	hlist_bl_set_first_rcu
 
-RCU:	Critical sections	Grace period		Barrier
+RCU::
+
+	Critical sections	Grace period		Barrier
 
 	rcu_read_lock		synchronize_net		rcu_barrier
 	rcu_read_unlock		synchronize_rcu
@@ -885,7 +905,9 @@ RCU:	Critical sections	Grace period		Barrier
 	rcu_dereference_check	kfree_rcu
 	rcu_dereference_protected
 
-bh:	Critical sections	Grace period		Barrier
+bh::
+
+	Critical sections	Grace period		Barrier
 
 	rcu_read_lock_bh	call_rcu		rcu_barrier
 	rcu_read_unlock_bh	synchronize_rcu
@@ -896,7 +918,9 @@ bh:	Critical sections	Grace period		Barrier
 	rcu_dereference_bh_protected
 	rcu_read_lock_bh_held
 
-sched:	Critical sections	Grace period		Barrier
+sched::
+
+	Critical sections	Grace period		Barrier
 
 	rcu_read_lock_sched	call_rcu		rcu_barrier
 	rcu_read_unlock_sched	synchronize_rcu
@@ -910,7 +934,9 @@ sched:	Critical sections	Grace period		Barrier
 	rcu_read_lock_sched_held
 
 
-SRCU:	Critical sections	Grace period		Barrier
+SRCU::
+
+	Critical sections	Grace period		Barrier
 
 	srcu_read_lock		call_srcu		srcu_barrier
 	srcu_read_unlock	synchronize_srcu
@@ -918,13 +944,14 @@ SRCU:	Critical sections	Grace period		Barrier
 	srcu_dereference_check
 	srcu_read_lock_held
 
-SRCU:	Initialization/cleanup
+SRCU: Initialization/cleanup::
+
 	DEFINE_SRCU
 	DEFINE_STATIC_SRCU
 	init_srcu_struct
 	cleanup_srcu_struct
 
-All:  lockdep-checked RCU-protected pointer access
+All: lockdep-checked RCU-protected pointer access::
 
 	rcu_access_pointer
 	rcu_dereference_raw
@@ -976,6 +1003,7 @@ the right tool for your job.
 
 
 8.  ANSWERS TO QUICK QUIZZES
+----------------------------
 
 Quick Quiz #1:	Why is this argument naive?  How could a deadlock
 		occur when using this algorithm in a real-world Linux
-- 
2.20.1

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-10-30 23:31 [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst tranmanphong at gmail.com (Phong Tran)
  2019-10-30 23:31 ` tranmanphong
@ 2019-10-31 22:54 ` paulmck at kernel.org (Paul E. McKenney)
  2019-10-31 22:54   ` Paul E. McKenney
                     ` (3 more replies)
  2019-11-02  8:31 ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  2 siblings, 4 replies; 23+ messages in thread
From: paulmck at kernel.org (Paul E. McKenney) @ 2019-10-31 22:54 UTC (permalink / raw)


On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> Sync the format with current state of kernel documentation.
> This change base on rcu-dev branch
> what changed:
> - Format bullet lists
> - Add literal blocks
> 
> Signed-off-by: Phong Tran <tranmanphong at gmail.com>

Queued and pushed with updated subject line and commit log, thank you!

Could you and Madhuparna please review and test each other's
.rst-conversion patches?

							Thanx, Paul

> ---
>  Documentation/RCU/index.rst                   |   1 +
>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>  2 files changed, 90 insertions(+), 61 deletions(-)
>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index 627128c230dc..b9b11481c727 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 3
>  
>     arrayRCU
> +   whatisRCU
>     rcu
>     listRCU
>     NMI-RCU
> diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst
> similarity index 91%
> rename from Documentation/RCU/whatisRCU.txt
> rename to Documentation/RCU/whatisRCU.rst
> index 58ba05c4d97f..70d0e4c21917 100644
> --- a/Documentation/RCU/whatisRCU.txt
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -1,15 +1,18 @@
> +.. _rcu_doc:
> +
>  What is RCU?  --  "Read, Copy, Update"
> +======================================
>  
>  Please note that the "What is RCU?" LWN series is an excellent place
>  to start learning about RCU:
>  
> -1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> -2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> -3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> -4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> -	2010 Big API Table           http://lwn.net/Articles/419086/
> -5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> -	2014 Big API Table           http://lwn.net/Articles/609973/
> +| 1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> +| 2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> +| 3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> +| 4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> +| 	2010 Big API Table           http://lwn.net/Articles/419086/
> +| 5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> +|	2014 Big API Table           http://lwn.net/Articles/609973/
>  
>  
>  What is RCU?
> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>  
>  
>  1.  RCU OVERVIEW
> +----------------
>  
>  The basic idea behind RCU is to split updates into "removal" and
>  "reclamation" phases.  The removal phase removes references to data items
> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>  
>  
>  2.  WHAT IS RCU'S CORE API?
> +---------------------------
>  
>  The core RCU API is quite small:
>  
> @@ -166,7 +171,7 @@ synchronize_rcu()
>  	read-side critical sections on all CPUs have completed.
>  	Note that synchronize_rcu() will -not- necessarily wait for
>  	any subsequent RCU read-side critical sections to complete.
> -	For example, consider the following sequence of events:
> +	For example, consider the following sequence of events::
>  
>  	         CPU 0                  CPU 1                 CPU 2
>  	     ----------------- ------------------------- ---------------
> @@ -248,13 +253,13 @@ rcu_dereference()
>  
>  	Common coding practice uses rcu_dereference() to copy an
>  	RCU-protected pointer to a local variable, then dereferences
> -	this local variable, for example as follows:
> +	this local variable, for example as follows::
>  
>  		p = rcu_dereference(head.next);
>  		return p->data;
>  
>  	However, in this case, one could just as easily combine these
> -	into one statement:
> +	into one statement::
>  
>  		return rcu_dereference(head.next)->data;
>  
> @@ -267,7 +272,7 @@ rcu_dereference()
>  
>  	Note that the value returned by rcu_dereference() is valid
>  	only within the enclosing RCU read-side critical section [1].
> -	For example, the following is -not- legal:
> +	For example, the following is -not- legal::
>  
>  		rcu_read_lock();
>  		p = rcu_dereference(head.next);
> @@ -315,6 +320,7 @@ rcu_dereference()
>  
>  The following diagram shows how each API communicates among the
>  reader, updater, and reclaimer.
> +::
>  
>  
>  	    rcu_assign_pointer()
> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>  
>  
>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> +-----------------------------------------------
>  
>  This section shows a simple use of the core RCU API to protect a
>  global pointer to a dynamically allocated structure.  More-typical
>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> +::
>  
>  	struct foo {
>  		int a;
> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>  
>  
>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> +--------------------------------------------
>  
>  In the example above, foo_update_a() blocks until a grace period elapses.
>  This is quite simple, but in some cases one cannot afford to wait so
>  long -- there might be other high-priority work to be done.
>  
>  In such cases, one uses call_rcu() rather than synchronize_rcu().
> -The call_rcu() API is as follows:
> +The call_rcu() API is as follows::
>  
>  	void call_rcu(struct rcu_head * head,
>  		      void (*func)(struct rcu_head *head));
> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>  This function invokes func(head) after a grace period has elapsed.
>  This invocation might happen from either softirq or process context,
>  so the function is not permitted to block.  The foo struct needs to
> -have an rcu_head structure added, perhaps as follows:
> +have an rcu_head structure added, perhaps as follows::
>  
>  	struct foo {
>  		int a;
> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>  		struct rcu_head rcu;
>  	};
>  
> -The foo_update_a() function might then be written as follows:
> +The foo_update_a() function might then be written as follows::
>  
>  	/*
>  	 * Create a new struct foo that is the same as the one currently
> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as follows:
>  		call_rcu(&old_fp->rcu, foo_reclaim);
>  	}
>  
> -The foo_reclaim() function might appear as follows:
> +The foo_reclaim() function might appear as follows::
>  
>  	void foo_reclaim(struct rcu_head *rp)
>  	{
> @@ -552,7 +561,7 @@ o	Use call_rcu() -after- removing a data element from an
>  
>  If the callback for call_rcu() is not doing anything more than calling
>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> -to avoid having to write your own callback:
> +to avoid having to write your own callback::
>  
>  	kfree_rcu(old_fp, rcu);
>  
> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules governing the use of RCU.
>  
>  
>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> +------------------------------------------------
>  
>  One of the nice things about RCU is that it has extremely simple "toy"
>  implementations that are a good first step towards understanding the
> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can deadlock.
>  However, it is probably the easiest implementation to relate to, so is
>  a good starting point.
>  
> -It is extremely simple:
> +It is extremely simple::
>  
>  	static DEFINE_RWLOCK(rcu_gp_mutex);
>  
> @@ -614,7 +624,7 @@ It is extremely simple:
>  
>  [You can ignore rcu_assign_pointer() and rcu_dereference() without missing
>  much.  But here are simplified versions anyway.  And whatever you do,
> -don't forget about them when submitting patches making use of RCU!]
> +don't forget about them when submitting patches making use of RCU!]::
>  
>  	#define rcu_assign_pointer(p, v) \
>  	({ \
> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that is based on
>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>  are the same as those shown in the preceding section, so they are omitted.
> +::
>  
>  	void rcu_read_lock(void) { }
>  
> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU read-side
>  
>  
>  6.  ANALOGY WITH READER-WRITER LOCKING
> +--------------------------------------
>  
>  Although RCU can be used in many different ways, a very common use of
>  RCU is analogous to reader-writer locking.  The following unified
>  diff shows how closely related RCU and reader-writer locking can be.
> +::
>  
>  	@@ -5,5 +5,5 @@ struct el {
>  	 	int data;
> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer locking can be.
>  		return 0;
>  	 }
>  
> -Or, for those who prefer a side-by-side listing:
> +Or, for those who prefer a side-by-side listing::
>  
>   1 struct el {                          1 struct el {
>   2   struct list_head list;             2   struct list_head list;
> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>   9 struct el head;                      9 struct el head;
>  
> - 1 int search(long key, int *result)    1 int search(long key, int *result)
> - 2 {                                    2 {
> - 3   struct list_head *lp;              3   struct list_head *lp;
> - 4   struct el *p;                      4   struct el *p;
> - 5                                      5
> - 6   read_lock(&listmutex);             6   rcu_read_lock();
> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
> - 8     if (p->key == key) {             8     if (p->key == key) {
> - 9       *result = p->data;             9       *result = p->data;
> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> -11       return 1;                     11       return 1;
> -12     }                               12     }
> -13   }                                 13   }
> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> -15   return 0;                         15   return 0;
> -16 }                                   16 }
> -
> - 1 int delete(long key)                 1 int delete(long key)
> - 2 {                                    2 {
> - 3   struct el *p;                      3   struct el *p;
> - 4                                      4
> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
> - 7     if (p->key == key) {             7     if (p->key == key) {
> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> -                                       10       synchronize_rcu();
> -10       kfree(p);                     11       kfree(p);
> -11       return 1;                     12       return 1;
> -12     }                               13     }
> -13   }                                 14   }
> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> -15   return 0;                         16   return 0;
> -16 }                                   17 }
> +::
> +
> +  1 int search(long key, int *result)    1 int search(long key, int *result)
> +  2 {                                    2 {
> +  3   struct list_head *lp;              3   struct list_head *lp;
> +  4   struct el *p;                      4   struct el *p;
> +  5                                      5
> +  6   read_lock(&listmutex);             6   rcu_read_lock();
> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
> +  8     if (p->key == key) {             8     if (p->key == key) {
> +  9       *result = p->data;             9       *result = p->data;
> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> + 11       return 1;                     11       return 1;
> + 12     }                               12     }
> + 13   }                                 13   }
> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> + 15   return 0;                         15   return 0;
> + 16 }                                   16 }
> +
> +::
> +
> +  1 int delete(long key)                 1 int delete(long key)
> +  2 {                                    2 {
> +  3   struct el *p;                      3   struct el *p;
> +  4                                      4
> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
> +  7     if (p->key == key) {             7     if (p->key == key) {
> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> +                                        10       synchronize_rcu();
> + 10       kfree(p);                     11       kfree(p);
> + 11       return 1;                     12       return 1;
> + 12     }                               13     }
> + 13   }                                 14   }
> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> + 15   return 0;                         16   return 0;
> + 16 }                                   17 }
>  
>  Either way, the differences are quite small.  Read-side locking moves
>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>  
>  
>  7.  FULL LIST OF RCU APIs
> +-------------------------
>  
>  The RCU APIs are documented in docbook-format header comments in the
>  Linux-kernel source code, but it helps to have a full list of the
>  APIs, since there does not appear to be a way to categorize them
>  in docbook.  Here is the list, by category.
>  
> -RCU list traversal:
> +RCU list traversal::
>  
>  	list_entry_rcu
>  	list_first_entry_rcu
> @@ -854,7 +872,7 @@ RCU list traversal:
>  	hlist_bl_first_rcu
>  	hlist_bl_for_each_entry_rcu
>  
> -RCU pointer/list update:
> +RCU pointer/list udate::
>  
>  	rcu_assign_pointer
>  	list_add_rcu
> @@ -876,7 +894,9 @@ RCU pointer/list update:
>  	hlist_bl_del_rcu
>  	hlist_bl_set_first_rcu
>  
> -RCU:	Critical sections	Grace period		Barrier
> +RCU::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock		synchronize_net		rcu_barrier
>  	rcu_read_unlock		synchronize_rcu
> @@ -885,7 +905,9 @@ RCU:	Critical sections	Grace period		Barrier
>  	rcu_dereference_check	kfree_rcu
>  	rcu_dereference_protected
>  
> -bh:	Critical sections	Grace period		Barrier
> +bh::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock_bh	call_rcu		rcu_barrier
>  	rcu_read_unlock_bh	synchronize_rcu
> @@ -896,7 +918,9 @@ bh:	Critical sections	Grace period		Barrier
>  	rcu_dereference_bh_protected
>  	rcu_read_lock_bh_held
>  
> -sched:	Critical sections	Grace period		Barrier
> +sched::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock_sched	call_rcu		rcu_barrier
>  	rcu_read_unlock_sched	synchronize_rcu
> @@ -910,7 +934,9 @@ sched:	Critical sections	Grace period		Barrier
>  	rcu_read_lock_sched_held
>  
>  
> -SRCU:	Critical sections	Grace period		Barrier
> +SRCU::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	srcu_read_lock		call_srcu		srcu_barrier
>  	srcu_read_unlock	synchronize_srcu
> @@ -918,13 +944,14 @@ SRCU:	Critical sections	Grace period		Barrier
>  	srcu_dereference_check
>  	srcu_read_lock_held
>  
> -SRCU:	Initialization/cleanup
> +SRCU: Initialization/cleanup::
> +
>  	DEFINE_SRCU
>  	DEFINE_STATIC_SRCU
>  	init_srcu_struct
>  	cleanup_srcu_struct
>  
> -All:  lockdep-checked RCU-protected pointer access
> +All: lockdep-checked RCU-protected pointer access::
>  
>  	rcu_access_pointer
>  	rcu_dereference_raw
> @@ -976,6 +1003,7 @@ the right tool for your job.
>  
>  
>  8.  ANSWERS TO QUICK QUIZZES
> +----------------------------
>  
>  Quick Quiz #1:	Why is this argument naive?  How could a deadlock
>  		occur when using this algorithm in a real-world Linux
> -- 
> 2.20.1
> 

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-10-31 22:54 ` paulmck at kernel.org (Paul E. McKenney)
  2019-10-31 22:54   ` Paul E. McKenney
@ 2019-10-31 22:54   ` paulmck
  2019-11-01  1:17   ` tranmanphong at gmail.com (Phong Tran)
  2019-11-01  3:33   ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  3 siblings, 0 replies; 23+ messages in thread
From: paulmck @ 2019-10-31 22:54 UTC (permalink / raw)


On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> Sync the format with current state of kernel documentation.
> This change base on rcu-dev branch
> what changed:
> - Format bullet lists
> - Add literal blocks
> 
> Signed-off-by: Phong Tran <tranmanphong at gmail.com>

Queued and pushed with updated subject line and commit log, thank you!

Could you and Madhuparna please review and test each other's
.rst-conversion patches?

							Thanx, Paul

> ---
>  Documentation/RCU/index.rst                   |   1 +
>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>  2 files changed, 90 insertions(+), 61 deletions(-)
>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index 627128c230dc..b9b11481c727 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 3
>  
>     arrayRCU
> +   whatisRCU
>     rcu
>     listRCU
>     NMI-RCU
> diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst
> similarity index 91%
> rename from Documentation/RCU/whatisRCU.txt
> rename to Documentation/RCU/whatisRCU.rst
> index 58ba05c4d97f..70d0e4c21917 100644
> --- a/Documentation/RCU/whatisRCU.txt
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -1,15 +1,18 @@
> +.. _rcu_doc:
> +
>  What is RCU?  --  "Read, Copy, Update"
> +======================================
>  
>  Please note that the "What is RCU?" LWN series is an excellent place
>  to start learning about RCU:
>  
> -1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> -2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> -3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> -4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> -	2010 Big API Table           http://lwn.net/Articles/419086/
> -5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> -	2014 Big API Table           http://lwn.net/Articles/609973/
> +| 1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> +| 2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> +| 3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> +| 4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> +| 	2010 Big API Table           http://lwn.net/Articles/419086/
> +| 5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> +|	2014 Big API Table           http://lwn.net/Articles/609973/
>  
>  
>  What is RCU?
> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>  
>  
>  1.  RCU OVERVIEW
> +----------------
>  
>  The basic idea behind RCU is to split updates into "removal" and
>  "reclamation" phases.  The removal phase removes references to data items
> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>  
>  
>  2.  WHAT IS RCU'S CORE API?
> +---------------------------
>  
>  The core RCU API is quite small:
>  
> @@ -166,7 +171,7 @@ synchronize_rcu()
>  	read-side critical sections on all CPUs have completed.
>  	Note that synchronize_rcu() will -not- necessarily wait for
>  	any subsequent RCU read-side critical sections to complete.
> -	For example, consider the following sequence of events:
> +	For example, consider the following sequence of events::
>  
>  	         CPU 0                  CPU 1                 CPU 2
>  	     ----------------- ------------------------- ---------------
> @@ -248,13 +253,13 @@ rcu_dereference()
>  
>  	Common coding practice uses rcu_dereference() to copy an
>  	RCU-protected pointer to a local variable, then dereferences
> -	this local variable, for example as follows:
> +	this local variable, for example as follows::
>  
>  		p = rcu_dereference(head.next);
>  		return p->data;
>  
>  	However, in this case, one could just as easily combine these
> -	into one statement:
> +	into one statement::
>  
>  		return rcu_dereference(head.next)->data;
>  
> @@ -267,7 +272,7 @@ rcu_dereference()
>  
>  	Note that the value returned by rcu_dereference() is valid
>  	only within the enclosing RCU read-side critical section [1].
> -	For example, the following is -not- legal:
> +	For example, the following is -not- legal::
>  
>  		rcu_read_lock();
>  		p = rcu_dereference(head.next);
> @@ -315,6 +320,7 @@ rcu_dereference()
>  
>  The following diagram shows how each API communicates among the
>  reader, updater, and reclaimer.
> +::
>  
>  
>  	    rcu_assign_pointer()
> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>  
>  
>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> +-----------------------------------------------
>  
>  This section shows a simple use of the core RCU API to protect a
>  global pointer to a dynamically allocated structure.  More-typical
>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> +::
>  
>  	struct foo {
>  		int a;
> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>  
>  
>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> +--------------------------------------------
>  
>  In the example above, foo_update_a() blocks until a grace period elapses.
>  This is quite simple, but in some cases one cannot afford to wait so
>  long -- there might be other high-priority work to be done.
>  
>  In such cases, one uses call_rcu() rather than synchronize_rcu().
> -The call_rcu() API is as follows:
> +The call_rcu() API is as follows::
>  
>  	void call_rcu(struct rcu_head * head,
>  		      void (*func)(struct rcu_head *head));
> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>  This function invokes func(head) after a grace period has elapsed.
>  This invocation might happen from either softirq or process context,
>  so the function is not permitted to block.  The foo struct needs to
> -have an rcu_head structure added, perhaps as follows:
> +have an rcu_head structure added, perhaps as follows::
>  
>  	struct foo {
>  		int a;
> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>  		struct rcu_head rcu;
>  	};
>  
> -The foo_update_a() function might then be written as follows:
> +The foo_update_a() function might then be written as follows::
>  
>  	/*
>  	 * Create a new struct foo that is the same as the one currently
> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as follows:
>  		call_rcu(&old_fp->rcu, foo_reclaim);
>  	}
>  
> -The foo_reclaim() function might appear as follows:
> +The foo_reclaim() function might appear as follows::
>  
>  	void foo_reclaim(struct rcu_head *rp)
>  	{
> @@ -552,7 +561,7 @@ o	Use call_rcu() -after- removing a data element from an
>  
>  If the callback for call_rcu() is not doing anything more than calling
>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> -to avoid having to write your own callback:
> +to avoid having to write your own callback::
>  
>  	kfree_rcu(old_fp, rcu);
>  
> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules governing the use of RCU.
>  
>  
>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> +------------------------------------------------
>  
>  One of the nice things about RCU is that it has extremely simple "toy"
>  implementations that are a good first step towards understanding the
> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can deadlock.
>  However, it is probably the easiest implementation to relate to, so is
>  a good starting point.
>  
> -It is extremely simple:
> +It is extremely simple::
>  
>  	static DEFINE_RWLOCK(rcu_gp_mutex);
>  
> @@ -614,7 +624,7 @@ It is extremely simple:
>  
>  [You can ignore rcu_assign_pointer() and rcu_dereference() without missing
>  much.  But here are simplified versions anyway.  And whatever you do,
> -don't forget about them when submitting patches making use of RCU!]
> +don't forget about them when submitting patches making use of RCU!]::
>  
>  	#define rcu_assign_pointer(p, v) \
>  	({ \
> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that is based on
>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>  are the same as those shown in the preceding section, so they are omitted.
> +::
>  
>  	void rcu_read_lock(void) { }
>  
> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU read-side
>  
>  
>  6.  ANALOGY WITH READER-WRITER LOCKING
> +--------------------------------------
>  
>  Although RCU can be used in many different ways, a very common use of
>  RCU is analogous to reader-writer locking.  The following unified
>  diff shows how closely related RCU and reader-writer locking can be.
> +::
>  
>  	@@ -5,5 +5,5 @@ struct el {
>  	 	int data;
> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer locking can be.
>  		return 0;
>  	 }
>  
> -Or, for those who prefer a side-by-side listing:
> +Or, for those who prefer a side-by-side listing::
>  
>   1 struct el {                          1 struct el {
>   2   struct list_head list;             2   struct list_head list;
> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>   9 struct el head;                      9 struct el head;
>  
> - 1 int search(long key, int *result)    1 int search(long key, int *result)
> - 2 {                                    2 {
> - 3   struct list_head *lp;              3   struct list_head *lp;
> - 4   struct el *p;                      4   struct el *p;
> - 5                                      5
> - 6   read_lock(&listmutex);             6   rcu_read_lock();
> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
> - 8     if (p->key == key) {             8     if (p->key == key) {
> - 9       *result = p->data;             9       *result = p->data;
> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> -11       return 1;                     11       return 1;
> -12     }                               12     }
> -13   }                                 13   }
> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> -15   return 0;                         15   return 0;
> -16 }                                   16 }
> -
> - 1 int delete(long key)                 1 int delete(long key)
> - 2 {                                    2 {
> - 3   struct el *p;                      3   struct el *p;
> - 4                                      4
> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
> - 7     if (p->key == key) {             7     if (p->key == key) {
> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> -                                       10       synchronize_rcu();
> -10       kfree(p);                     11       kfree(p);
> -11       return 1;                     12       return 1;
> -12     }                               13     }
> -13   }                                 14   }
> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> -15   return 0;                         16   return 0;
> -16 }                                   17 }
> +::
> +
> +  1 int search(long key, int *result)    1 int search(long key, int *result)
> +  2 {                                    2 {
> +  3   struct list_head *lp;              3   struct list_head *lp;
> +  4   struct el *p;                      4   struct el *p;
> +  5                                      5
> +  6   read_lock(&listmutex);             6   rcu_read_lock();
> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
> +  8     if (p->key == key) {             8     if (p->key == key) {
> +  9       *result = p->data;             9       *result = p->data;
> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> + 11       return 1;                     11       return 1;
> + 12     }                               12     }
> + 13   }                                 13   }
> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> + 15   return 0;                         15   return 0;
> + 16 }                                   16 }
> +
> +::
> +
> +  1 int delete(long key)                 1 int delete(long key)
> +  2 {                                    2 {
> +  3   struct el *p;                      3   struct el *p;
> +  4                                      4
> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
> +  7     if (p->key == key) {             7     if (p->key == key) {
> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> +                                        10       synchronize_rcu();
> + 10       kfree(p);                     11       kfree(p);
> + 11       return 1;                     12       return 1;
> + 12     }                               13     }
> + 13   }                                 14   }
> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> + 15   return 0;                         16   return 0;
> + 16 }                                   17 }
>  
>  Either way, the differences are quite small.  Read-side locking moves
>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>  
>  
>  7.  FULL LIST OF RCU APIs
> +-------------------------
>  
>  The RCU APIs are documented in docbook-format header comments in the
>  Linux-kernel source code, but it helps to have a full list of the
>  APIs, since there does not appear to be a way to categorize them
>  in docbook.  Here is the list, by category.
>  
> -RCU list traversal:
> +RCU list traversal::
>  
>  	list_entry_rcu
>  	list_first_entry_rcu
> @@ -854,7 +872,7 @@ RCU list traversal:
>  	hlist_bl_first_rcu
>  	hlist_bl_for_each_entry_rcu
>  
> -RCU pointer/list update:
> +RCU pointer/list udate::
>  
>  	rcu_assign_pointer
>  	list_add_rcu
> @@ -876,7 +894,9 @@ RCU pointer/list update:
>  	hlist_bl_del_rcu
>  	hlist_bl_set_first_rcu
>  
> -RCU:	Critical sections	Grace period		Barrier
> +RCU::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock		synchronize_net		rcu_barrier
>  	rcu_read_unlock		synchronize_rcu
> @@ -885,7 +905,9 @@ RCU:	Critical sections	Grace period		Barrier
>  	rcu_dereference_check	kfree_rcu
>  	rcu_dereference_protected
>  
> -bh:	Critical sections	Grace period		Barrier
> +bh::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock_bh	call_rcu		rcu_barrier
>  	rcu_read_unlock_bh	synchronize_rcu
> @@ -896,7 +918,9 @@ bh:	Critical sections	Grace period		Barrier
>  	rcu_dereference_bh_protected
>  	rcu_read_lock_bh_held
>  
> -sched:	Critical sections	Grace period		Barrier
> +sched::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock_sched	call_rcu		rcu_barrier
>  	rcu_read_unlock_sched	synchronize_rcu
> @@ -910,7 +934,9 @@ sched:	Critical sections	Grace period		Barrier
>  	rcu_read_lock_sched_held
>  
>  
> -SRCU:	Critical sections	Grace period		Barrier
> +SRCU::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	srcu_read_lock		call_srcu		srcu_barrier
>  	srcu_read_unlock	synchronize_srcu
> @@ -918,13 +944,14 @@ SRCU:	Critical sections	Grace period		Barrier
>  	srcu_dereference_check
>  	srcu_read_lock_held
>  
> -SRCU:	Initialization/cleanup
> +SRCU: Initialization/cleanup::
> +
>  	DEFINE_SRCU
>  	DEFINE_STATIC_SRCU
>  	init_srcu_struct
>  	cleanup_srcu_struct
>  
> -All:  lockdep-checked RCU-protected pointer access
> +All: lockdep-checked RCU-protected pointer access::
>  
>  	rcu_access_pointer
>  	rcu_dereference_raw
> @@ -976,6 +1003,7 @@ the right tool for your job.
>  
>  
>  8.  ANSWERS TO QUICK QUIZZES
> +----------------------------
>  
>  Quick Quiz #1:	Why is this argument naive?  How could a deadlock
>  		occur when using this algorithm in a real-world Linux
> -- 
> 2.20.1
> 

^ permalink raw reply	[flat|nested] 23+ messages in thread

* Re: [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-10-31 22:54 ` paulmck at kernel.org (Paul E. McKenney)
@ 2019-10-31 22:54   ` Paul E. McKenney
  2019-10-31 22:54   ` paulmck
                     ` (2 subsequent siblings)
  3 siblings, 0 replies; 23+ messages in thread
From: Paul E. McKenney @ 2019-10-31 22:54 UTC (permalink / raw)
  To: Phong Tran
  Cc: corbet, linux-doc, jiangshanlai, josh, rostedt, linux-kernel,
	rcu, mathieu.desnoyers, joel, linux-kernel-mentees

On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> Sync the format with current state of kernel documentation.
> This change base on rcu-dev branch
> what changed:
> - Format bullet lists
> - Add literal blocks
> 
> Signed-off-by: Phong Tran <tranmanphong@gmail.com>

Queued and pushed with updated subject line and commit log, thank you!

Could you and Madhuparna please review and test each other's
.rst-conversion patches?

							Thanx, Paul

> ---
>  Documentation/RCU/index.rst                   |   1 +
>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>  2 files changed, 90 insertions(+), 61 deletions(-)
>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> 
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index 627128c230dc..b9b11481c727 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 3
>  
>     arrayRCU
> +   whatisRCU
>     rcu
>     listRCU
>     NMI-RCU
> diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst
> similarity index 91%
> rename from Documentation/RCU/whatisRCU.txt
> rename to Documentation/RCU/whatisRCU.rst
> index 58ba05c4d97f..70d0e4c21917 100644
> --- a/Documentation/RCU/whatisRCU.txt
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -1,15 +1,18 @@
> +.. _rcu_doc:
> +
>  What is RCU?  --  "Read, Copy, Update"
> +======================================
>  
>  Please note that the "What is RCU?" LWN series is an excellent place
>  to start learning about RCU:
>  
> -1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> -2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> -3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> -4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> -	2010 Big API Table           http://lwn.net/Articles/419086/
> -5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> -	2014 Big API Table           http://lwn.net/Articles/609973/
> +| 1.	What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> +| 2.	What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> +| 3.	RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> +| 4.	The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> +| 	2010 Big API Table           http://lwn.net/Articles/419086/
> +| 5.	The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> +|	2014 Big API Table           http://lwn.net/Articles/609973/
>  
>  
>  What is RCU?
> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>  
>  
>  1.  RCU OVERVIEW
> +----------------
>  
>  The basic idea behind RCU is to split updates into "removal" and
>  "reclamation" phases.  The removal phase removes references to data items
> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>  
>  
>  2.  WHAT IS RCU'S CORE API?
> +---------------------------
>  
>  The core RCU API is quite small:
>  
> @@ -166,7 +171,7 @@ synchronize_rcu()
>  	read-side critical sections on all CPUs have completed.
>  	Note that synchronize_rcu() will -not- necessarily wait for
>  	any subsequent RCU read-side critical sections to complete.
> -	For example, consider the following sequence of events:
> +	For example, consider the following sequence of events::
>  
>  	         CPU 0                  CPU 1                 CPU 2
>  	     ----------------- ------------------------- ---------------
> @@ -248,13 +253,13 @@ rcu_dereference()
>  
>  	Common coding practice uses rcu_dereference() to copy an
>  	RCU-protected pointer to a local variable, then dereferences
> -	this local variable, for example as follows:
> +	this local variable, for example as follows::
>  
>  		p = rcu_dereference(head.next);
>  		return p->data;
>  
>  	However, in this case, one could just as easily combine these
> -	into one statement:
> +	into one statement::
>  
>  		return rcu_dereference(head.next)->data;
>  
> @@ -267,7 +272,7 @@ rcu_dereference()
>  
>  	Note that the value returned by rcu_dereference() is valid
>  	only within the enclosing RCU read-side critical section [1].
> -	For example, the following is -not- legal:
> +	For example, the following is -not- legal::
>  
>  		rcu_read_lock();
>  		p = rcu_dereference(head.next);
> @@ -315,6 +320,7 @@ rcu_dereference()
>  
>  The following diagram shows how each API communicates among the
>  reader, updater, and reclaimer.
> +::
>  
>  
>  	    rcu_assign_pointer()
> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>  
>  
>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> +-----------------------------------------------
>  
>  This section shows a simple use of the core RCU API to protect a
>  global pointer to a dynamically allocated structure.  More-typical
>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> +::
>  
>  	struct foo {
>  		int a;
> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>  
>  
>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> +--------------------------------------------
>  
>  In the example above, foo_update_a() blocks until a grace period elapses.
>  This is quite simple, but in some cases one cannot afford to wait so
>  long -- there might be other high-priority work to be done.
>  
>  In such cases, one uses call_rcu() rather than synchronize_rcu().
> -The call_rcu() API is as follows:
> +The call_rcu() API is as follows::
>  
>  	void call_rcu(struct rcu_head * head,
>  		      void (*func)(struct rcu_head *head));
> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>  This function invokes func(head) after a grace period has elapsed.
>  This invocation might happen from either softirq or process context,
>  so the function is not permitted to block.  The foo struct needs to
> -have an rcu_head structure added, perhaps as follows:
> +have an rcu_head structure added, perhaps as follows::
>  
>  	struct foo {
>  		int a;
> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>  		struct rcu_head rcu;
>  	};
>  
> -The foo_update_a() function might then be written as follows:
> +The foo_update_a() function might then be written as follows::
>  
>  	/*
>  	 * Create a new struct foo that is the same as the one currently
> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as follows:
>  		call_rcu(&old_fp->rcu, foo_reclaim);
>  	}
>  
> -The foo_reclaim() function might appear as follows:
> +The foo_reclaim() function might appear as follows::
>  
>  	void foo_reclaim(struct rcu_head *rp)
>  	{
> @@ -552,7 +561,7 @@ o	Use call_rcu() -after- removing a data element from an
>  
>  If the callback for call_rcu() is not doing anything more than calling
>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> -to avoid having to write your own callback:
> +to avoid having to write your own callback::
>  
>  	kfree_rcu(old_fp, rcu);
>  
> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules governing the use of RCU.
>  
>  
>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> +------------------------------------------------
>  
>  One of the nice things about RCU is that it has extremely simple "toy"
>  implementations that are a good first step towards understanding the
> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can deadlock.
>  However, it is probably the easiest implementation to relate to, so is
>  a good starting point.
>  
> -It is extremely simple:
> +It is extremely simple::
>  
>  	static DEFINE_RWLOCK(rcu_gp_mutex);
>  
> @@ -614,7 +624,7 @@ It is extremely simple:
>  
>  [You can ignore rcu_assign_pointer() and rcu_dereference() without missing
>  much.  But here are simplified versions anyway.  And whatever you do,
> -don't forget about them when submitting patches making use of RCU!]
> +don't forget about them when submitting patches making use of RCU!]::
>  
>  	#define rcu_assign_pointer(p, v) \
>  	({ \
> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that is based on
>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>  are the same as those shown in the preceding section, so they are omitted.
> +::
>  
>  	void rcu_read_lock(void) { }
>  
> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU read-side
>  
>  
>  6.  ANALOGY WITH READER-WRITER LOCKING
> +--------------------------------------
>  
>  Although RCU can be used in many different ways, a very common use of
>  RCU is analogous to reader-writer locking.  The following unified
>  diff shows how closely related RCU and reader-writer locking can be.
> +::
>  
>  	@@ -5,5 +5,5 @@ struct el {
>  	 	int data;
> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer locking can be.
>  		return 0;
>  	 }
>  
> -Or, for those who prefer a side-by-side listing:
> +Or, for those who prefer a side-by-side listing::
>  
>   1 struct el {                          1 struct el {
>   2   struct list_head list;             2   struct list_head list;
> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>   9 struct el head;                      9 struct el head;
>  
> - 1 int search(long key, int *result)    1 int search(long key, int *result)
> - 2 {                                    2 {
> - 3   struct list_head *lp;              3   struct list_head *lp;
> - 4   struct el *p;                      4   struct el *p;
> - 5                                      5
> - 6   read_lock(&listmutex);             6   rcu_read_lock();
> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
> - 8     if (p->key == key) {             8     if (p->key == key) {
> - 9       *result = p->data;             9       *result = p->data;
> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> -11       return 1;                     11       return 1;
> -12     }                               12     }
> -13   }                                 13   }
> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> -15   return 0;                         15   return 0;
> -16 }                                   16 }
> -
> - 1 int delete(long key)                 1 int delete(long key)
> - 2 {                                    2 {
> - 3   struct el *p;                      3   struct el *p;
> - 4                                      4
> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
> - 7     if (p->key == key) {             7     if (p->key == key) {
> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> -                                       10       synchronize_rcu();
> -10       kfree(p);                     11       kfree(p);
> -11       return 1;                     12       return 1;
> -12     }                               13     }
> -13   }                                 14   }
> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> -15   return 0;                         16   return 0;
> -16 }                                   17 }
> +::
> +
> +  1 int search(long key, int *result)    1 int search(long key, int *result)
> +  2 {                                    2 {
> +  3   struct list_head *lp;              3   struct list_head *lp;
> +  4   struct el *p;                      4   struct el *p;
> +  5                                      5
> +  6   read_lock(&listmutex);             6   rcu_read_lock();
> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {
> +  8     if (p->key == key) {             8     if (p->key == key) {
> +  9       *result = p->data;             9       *result = p->data;
> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> + 11       return 1;                     11       return 1;
> + 12     }                               12     }
> + 13   }                                 13   }
> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> + 15   return 0;                         15   return 0;
> + 16 }                                   16 }
> +
> +::
> +
> +  1 int delete(long key)                 1 int delete(long key)
> +  2 {                                    2 {
> +  3   struct el *p;                      3   struct el *p;
> +  4                                      4
> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {
> +  7     if (p->key == key) {             7     if (p->key == key) {
> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> +                                        10       synchronize_rcu();
> + 10       kfree(p);                     11       kfree(p);
> + 11       return 1;                     12       return 1;
> + 12     }                               13     }
> + 13   }                                 14   }
> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> + 15   return 0;                         16   return 0;
> + 16 }                                   17 }
>  
>  Either way, the differences are quite small.  Read-side locking moves
>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>  
>  
>  7.  FULL LIST OF RCU APIs
> +-------------------------
>  
>  The RCU APIs are documented in docbook-format header comments in the
>  Linux-kernel source code, but it helps to have a full list of the
>  APIs, since there does not appear to be a way to categorize them
>  in docbook.  Here is the list, by category.
>  
> -RCU list traversal:
> +RCU list traversal::
>  
>  	list_entry_rcu
>  	list_first_entry_rcu
> @@ -854,7 +872,7 @@ RCU list traversal:
>  	hlist_bl_first_rcu
>  	hlist_bl_for_each_entry_rcu
>  
> -RCU pointer/list update:
> +RCU pointer/list udate::
>  
>  	rcu_assign_pointer
>  	list_add_rcu
> @@ -876,7 +894,9 @@ RCU pointer/list update:
>  	hlist_bl_del_rcu
>  	hlist_bl_set_first_rcu
>  
> -RCU:	Critical sections	Grace period		Barrier
> +RCU::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock		synchronize_net		rcu_barrier
>  	rcu_read_unlock		synchronize_rcu
> @@ -885,7 +905,9 @@ RCU:	Critical sections	Grace period		Barrier
>  	rcu_dereference_check	kfree_rcu
>  	rcu_dereference_protected
>  
> -bh:	Critical sections	Grace period		Barrier
> +bh::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock_bh	call_rcu		rcu_barrier
>  	rcu_read_unlock_bh	synchronize_rcu
> @@ -896,7 +918,9 @@ bh:	Critical sections	Grace period		Barrier
>  	rcu_dereference_bh_protected
>  	rcu_read_lock_bh_held
>  
> -sched:	Critical sections	Grace period		Barrier
> +sched::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	rcu_read_lock_sched	call_rcu		rcu_barrier
>  	rcu_read_unlock_sched	synchronize_rcu
> @@ -910,7 +934,9 @@ sched:	Critical sections	Grace period		Barrier
>  	rcu_read_lock_sched_held
>  
>  
> -SRCU:	Critical sections	Grace period		Barrier
> +SRCU::
> +
> +	Critical sections	Grace period		Barrier
>  
>  	srcu_read_lock		call_srcu		srcu_barrier
>  	srcu_read_unlock	synchronize_srcu
> @@ -918,13 +944,14 @@ SRCU:	Critical sections	Grace period		Barrier
>  	srcu_dereference_check
>  	srcu_read_lock_held
>  
> -SRCU:	Initialization/cleanup
> +SRCU: Initialization/cleanup::
> +
>  	DEFINE_SRCU
>  	DEFINE_STATIC_SRCU
>  	init_srcu_struct
>  	cleanup_srcu_struct
>  
> -All:  lockdep-checked RCU-protected pointer access
> +All: lockdep-checked RCU-protected pointer access::
>  
>  	rcu_access_pointer
>  	rcu_dereference_raw
> @@ -976,6 +1003,7 @@ the right tool for your job.
>  
>  
>  8.  ANSWERS TO QUICK QUIZZES
> +----------------------------
>  
>  Quick Quiz #1:	Why is this argument naive?  How could a deadlock
>  		occur when using this algorithm in a real-world Linux
> -- 
> 2.20.1
> 
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-10-31 22:54 ` paulmck at kernel.org (Paul E. McKenney)
  2019-10-31 22:54   ` Paul E. McKenney
  2019-10-31 22:54   ` paulmck
@ 2019-11-01  1:17   ` tranmanphong at gmail.com (Phong Tran)
  2019-11-01  1:17     ` Phong Tran
                       ` (2 more replies)
  2019-11-01  3:33   ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  3 siblings, 3 replies; 23+ messages in thread
From: tranmanphong at gmail.com (Phong Tran) @ 2019-11-01  1:17 UTC (permalink / raw)


Hi Paul,
On 11/1/19 5:54 AM, Paul E. McKenney wrote:
> Could you and Madhuparna please review and test each other's
> .rst-conversion patches?
> 

It's fine.
pull and "make SPHINXDIRS="RCU" htmldocs pdfdocs" rcu dev branch
without error or warning.

thanks,
Phong.

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  1:17   ` tranmanphong at gmail.com (Phong Tran)
  2019-11-01  1:17     ` Phong Tran
@ 2019-11-01  1:17     ` tranmanphong
  2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
  2 siblings, 0 replies; 23+ messages in thread
From: tranmanphong @ 2019-11-01  1:17 UTC (permalink / raw)


Hi Paul,
On 11/1/19 5:54 AM, Paul E. McKenney wrote:
> Could you and Madhuparna please review and test each other's
> .rst-conversion patches?
> 

It's fine.
pull and "make SPHINXDIRS="RCU" htmldocs pdfdocs" rcu dev branch
without error or warning.

thanks,
Phong.

^ permalink raw reply	[flat|nested] 23+ messages in thread

* Re: [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  1:17   ` tranmanphong at gmail.com (Phong Tran)
@ 2019-11-01  1:17     ` Phong Tran
  2019-11-01  1:17     ` tranmanphong
  2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
  2 siblings, 0 replies; 23+ messages in thread
From: Phong Tran @ 2019-11-01  1:17 UTC (permalink / raw)
  To: paulmck, madhuparnabhowmik04
  Cc: corbet, linux-doc, jiangshanlai, josh, rostedt, linux-kernel,
	rcu, mathieu.desnoyers, joel, linux-kernel-mentees

Hi Paul,
On 11/1/19 5:54 AM, Paul E. McKenney wrote:
> Could you and Madhuparna please review and test each other's
> .rst-conversion patches?
> 

It's fine.
pull and "make SPHINXDIRS="RCU" htmldocs pdfdocs" rcu dev branch
without error or warning.

thanks,
Phong.
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-10-31 22:54 ` paulmck at kernel.org (Paul E. McKenney)
                     ` (2 preceding siblings ...)
  2019-11-01  1:17   ` tranmanphong at gmail.com (Phong Tran)
@ 2019-11-01  3:33   ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  2019-11-01  3:33     ` madhuparnabhowmik04
                       ` (2 more replies)
  3 siblings, 3 replies; 23+ messages in thread
From: madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik) @ 2019-11-01  3:33 UTC (permalink / raw)


On Fri, 1 Nov, 2019, 4:24 AM Paul E. McKenney, <paulmck at kernel.org> wrote:

> On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> > Sync the format with current state of kernel documentation.
> > This change base on rcu-dev branch
> > what changed:
> > - Format bullet lists
> > - Add literal blocks
> >
> > Signed-off-by: Phong Tran <tranmanphong at gmail.com>
>
> Queued and pushed with updated subject line and commit log, thank you!
>
> Could you and Madhuparna please review and test each other's
> .rst-conversion patches?
>

Sure, I will do it.
Regards
Madhuparna


>                                                         Thanx, Paul
>
> > ---
> >  Documentation/RCU/index.rst                   |   1 +
> >  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
> >  2 files changed, 90 insertions(+), 61 deletions(-)
> >  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> >
> > diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> > index 627128c230dc..b9b11481c727 100644
> > --- a/Documentation/RCU/index.rst
> > +++ b/Documentation/RCU/index.rst
> > @@ -8,6 +8,7 @@ RCU concepts
> >     :maxdepth: 3
> >
> >     arrayRCU
> > +   whatisRCU
> >     rcu
> >     listRCU
> >     NMI-RCU
> > diff --git a/Documentation/RCU/whatisRCU.txt
> b/Documentation/RCU/whatisRCU.rst
> > similarity index 91%
> > rename from Documentation/RCU/whatisRCU.txt
> > rename to Documentation/RCU/whatisRCU.rst
> > index 58ba05c4d97f..70d0e4c21917 100644
> > --- a/Documentation/RCU/whatisRCU.txt
> > +++ b/Documentation/RCU/whatisRCU.rst
> > @@ -1,15 +1,18 @@
> > +.. _rcu_doc:
> > +
> >  What is RCU?  --  "Read, Copy, Update"
> > +======================================
> >
> >  Please note that the "What is RCU?" LWN series is an excellent place
> >  to start learning about RCU:
> >
> > -1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > -2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > -3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > -4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > -     2010 Big API Table           http://lwn.net/Articles/419086/
> > -5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > -     2014 Big API Table           http://lwn.net/Articles/609973/
> > +| 1. What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > +| 2. What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > +| 3. RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > +| 4. The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > +|    2010 Big API Table           http://lwn.net/Articles/419086/
> > +| 5. The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > +|    2014 Big API Table           http://lwn.net/Articles/609973/
> >
> >
> >  What is RCU?
> > @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
> >
> >
> >  1.  RCU OVERVIEW
> > +----------------
> >
> >  The basic idea behind RCU is to split updates into "removal" and
> >  "reclamation" phases.  The removal phase removes references to data
> items
> > @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
> >
> >
> >  2.  WHAT IS RCU'S CORE API?
> > +---------------------------
> >
> >  The core RCU API is quite small:
> >
> > @@ -166,7 +171,7 @@ synchronize_rcu()
> >       read-side critical sections on all CPUs have completed.
> >       Note that synchronize_rcu() will -not- necessarily wait for
> >       any subsequent RCU read-side critical sections to complete.
> > -     For example, consider the following sequence of events:
> > +     For example, consider the following sequence of events::
> >
> >                CPU 0                  CPU 1                 CPU 2
> >            ----------------- ------------------------- ---------------
> > @@ -248,13 +253,13 @@ rcu_dereference()
> >
> >       Common coding practice uses rcu_dereference() to copy an
> >       RCU-protected pointer to a local variable, then dereferences
> > -     this local variable, for example as follows:
> > +     this local variable, for example as follows::
> >
> >               p = rcu_dereference(head.next);
> >               return p->data;
> >
> >       However, in this case, one could just as easily combine these
> > -     into one statement:
> > +     into one statement::
> >
> >               return rcu_dereference(head.next)->data;
> >
> > @@ -267,7 +272,7 @@ rcu_dereference()
> >
> >       Note that the value returned by rcu_dereference() is valid
> >       only within the enclosing RCU read-side critical section [1].
> > -     For example, the following is -not- legal:
> > +     For example, the following is -not- legal::
> >
> >               rcu_read_lock();
> >               p = rcu_dereference(head.next);
> > @@ -315,6 +320,7 @@ rcu_dereference()
> >
> >  The following diagram shows how each API communicates among the
> >  reader, updater, and reclaimer.
> > +::
> >
> >
> >           rcu_assign_pointer()
> > @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
> >
> >
> >  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> > +-----------------------------------------------
> >
> >  This section shows a simple use of the core RCU API to protect a
> >  global pointer to a dynamically allocated structure.  More-typical
> >  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> > +::
> >
> >       struct foo {
> >               int a;
> > @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
> >
> >
> >  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> > +--------------------------------------------
> >
> >  In the example above, foo_update_a() blocks until a grace period
> elapses.
> >  This is quite simple, but in some cases one cannot afford to wait so
> >  long -- there might be other high-priority work to be done.
> >
> >  In such cases, one uses call_rcu() rather than synchronize_rcu().
> > -The call_rcu() API is as follows:
> > +The call_rcu() API is as follows::
> >
> >       void call_rcu(struct rcu_head * head,
> >                     void (*func)(struct rcu_head *head));
> > @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
> >  This function invokes func(head) after a grace period has elapsed.
> >  This invocation might happen from either softirq or process context,
> >  so the function is not permitted to block.  The foo struct needs to
> > -have an rcu_head structure added, perhaps as follows:
> > +have an rcu_head structure added, perhaps as follows::
> >
> >       struct foo {
> >               int a;
> > @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
> >               struct rcu_head rcu;
> >       };
> >
> > -The foo_update_a() function might then be written as follows:
> > +The foo_update_a() function might then be written as follows::
> >
> >       /*
> >        * Create a new struct foo that is the same as the one currently
> > @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> follows:
> >               call_rcu(&old_fp->rcu, foo_reclaim);
> >       }
> >
> > -The foo_reclaim() function might appear as follows:
> > +The foo_reclaim() function might appear as follows::
> >
> >       void foo_reclaim(struct rcu_head *rp)
> >       {
> > @@ -552,7 +561,7 @@ o Use call_rcu() -after- removing a data element
> from an
> >
> >  If the callback for call_rcu() is not doing anything more than calling
> >  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> > -to avoid having to write your own callback:
> > +to avoid having to write your own callback::
> >
> >       kfree_rcu(old_fp, rcu);
> >
> > @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> governing the use of RCU.
> >
> >
> >  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> > +------------------------------------------------
> >
> >  One of the nice things about RCU is that it has extremely simple "toy"
> >  implementations that are a good first step towards understanding the
> > @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> deadlock.
> >  However, it is probably the easiest implementation to relate to, so is
> >  a good starting point.
> >
> > -It is extremely simple:
> > +It is extremely simple::
> >
> >       static DEFINE_RWLOCK(rcu_gp_mutex);
> >
> > @@ -614,7 +624,7 @@ It is extremely simple:
> >
> >  [You can ignore rcu_assign_pointer() and rcu_dereference() without
> missing
> >  much.  But here are simplified versions anyway.  And whatever you do,
> > -don't forget about them when submitting patches making use of RCU!]
> > +don't forget about them when submitting patches making use of RCU!]::
> >
> >       #define rcu_assign_pointer(p, v) \
> >       ({ \
> > @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation
> that is based on
> >  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
> >  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
> >  are the same as those shown in the preceding section, so they are
> omitted.
> > +::
> >
> >       void rcu_read_lock(void) { }
> >
> > @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an
> RCU read-side
> >
> >
> >  6.  ANALOGY WITH READER-WRITER LOCKING
> > +--------------------------------------
> >
> >  Although RCU can be used in many different ways, a very common use of
> >  RCU is analogous to reader-writer locking.  The following unified
> >  diff shows how closely related RCU and reader-writer locking can be.
> > +::
> >
> >       @@ -5,5 +5,5 @@ struct el {
> >               int data;
> > @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> locking can be.
> >               return 0;
> >        }
> >
> > -Or, for those who prefer a side-by-side listing:
> > +Or, for those who prefer a side-by-side listing::
> >
> >   1 struct el {                          1 struct el {
> >   2   struct list_head list;             2   struct list_head list;
> > @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
> >   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
> >   9 struct el head;                      9 struct el head;
> >
> > - 1 int search(long key, int *result)    1 int search(long key, int
> *result)
> > - 2 {                                    2 {
> > - 3   struct list_head *lp;              3   struct list_head *lp;
> > - 4   struct el *p;                      4   struct el *p;
> > - 5                                      5
> > - 6   read_lock(&listmutex);             6   rcu_read_lock();
> > - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> > - 8     if (p->key == key) {             8     if (p->key == key) {
> > - 9       *result = p->data;             9       *result = p->data;
> > -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > -11       return 1;                     11       return 1;
> > -12     }                               12     }
> > -13   }                                 13   }
> > -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > -15   return 0;                         15   return 0;
> > -16 }                                   16 }
> > -
> > - 1 int delete(long key)                 1 int delete(long key)
> > - 2 {                                    2 {
> > - 3   struct el *p;                      3   struct el *p;
> > - 4                                      4
> > - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> head, lp) {
> > - 7     if (p->key == key) {             7     if (p->key == key) {
> > - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> > -                                       10       synchronize_rcu();
> > -10       kfree(p);                     11       kfree(p);
> > -11       return 1;                     12       return 1;
> > -12     }                               13     }
> > -13   }                                 14   }
> > -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > -15   return 0;                         16   return 0;
> > -16 }                                   17 }
> > +::
> > +
> > +  1 int search(long key, int *result)    1 int search(long key, int
> *result)
> > +  2 {                                    2 {
> > +  3   struct list_head *lp;              3   struct list_head *lp;
> > +  4   struct el *p;                      4   struct el *p;
> > +  5                                      5
> > +  6   read_lock(&listmutex);             6   rcu_read_lock();
> > +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> > +  8     if (p->key == key) {             8     if (p->key == key) {
> > +  9       *result = p->data;             9       *result = p->data;
> > + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > + 11       return 1;                     11       return 1;
> > + 12     }                               12     }
> > + 13   }                                 13   }
> > + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > + 15   return 0;                         15   return 0;
> > + 16 }                                   16 }
> > +
> > +::
> > +
> > +  1 int delete(long key)                 1 int delete(long key)
> > +  2 {                                    2 {
> > +  3   struct el *p;                      3   struct el *p;
> > +  4                                      4
> > +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> head, lp) {
> > +  7     if (p->key == key) {             7     if (p->key == key) {
> > +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > +  9       write_unlock(&listmutex);      9
>  spin_unlock(&listmutex);
> > +                                        10       synchronize_rcu();
> > + 10       kfree(p);                     11       kfree(p);
> > + 11       return 1;                     12       return 1;
> > + 12     }                               13     }
> > + 13   }                                 14   }
> > + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > + 15   return 0;                         16   return 0;
> > + 16 }                                   17 }
> >
> >  Either way, the differences are quite small.  Read-side locking moves
> >  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> > @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
> >
> >
> >  7.  FULL LIST OF RCU APIs
> > +-------------------------
> >
> >  The RCU APIs are documented in docbook-format header comments in the
> >  Linux-kernel source code, but it helps to have a full list of the
> >  APIs, since there does not appear to be a way to categorize them
> >  in docbook.  Here is the list, by category.
> >
> > -RCU list traversal:
> > +RCU list traversal::
> >
> >       list_entry_rcu
> >       list_first_entry_rcu
> > @@ -854,7 +872,7 @@ RCU list traversal:
> >       hlist_bl_first_rcu
> >       hlist_bl_for_each_entry_rcu
> >
> > -RCU pointer/list update:
> > +RCU pointer/list udate::
> >
> >       rcu_assign_pointer
> >       list_add_rcu
> > @@ -876,7 +894,9 @@ RCU pointer/list update:
> >       hlist_bl_del_rcu
> >       hlist_bl_set_first_rcu
> >
> > -RCU: Critical sections       Grace period            Barrier
> > +RCU::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock           synchronize_net         rcu_barrier
> >       rcu_read_unlock         synchronize_rcu
> > @@ -885,7 +905,9 @@ RCU:      Critical sections       Grace period
>       Barrier
> >       rcu_dereference_check   kfree_rcu
> >       rcu_dereference_protected
> >
> > -bh:  Critical sections       Grace period            Barrier
> > +bh::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock_bh        call_rcu                rcu_barrier
> >       rcu_read_unlock_bh      synchronize_rcu
> > @@ -896,7 +918,9 @@ bh:       Critical sections       Grace period
>       Barrier
> >       rcu_dereference_bh_protected
> >       rcu_read_lock_bh_held
> >
> > -sched:       Critical sections       Grace period            Barrier
> > +sched::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock_sched     call_rcu                rcu_barrier
> >       rcu_read_unlock_sched   synchronize_rcu
> > @@ -910,7 +934,9 @@ sched:    Critical sections       Grace period
>       Barrier
> >       rcu_read_lock_sched_held
> >
> >
> > -SRCU:        Critical sections       Grace period            Barrier
> > +SRCU::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       srcu_read_lock          call_srcu               srcu_barrier
> >       srcu_read_unlock        synchronize_srcu
> > @@ -918,13 +944,14 @@ SRCU:   Critical sections       Grace period
>       Barrier
> >       srcu_dereference_check
> >       srcu_read_lock_held
> >
> > -SRCU:        Initialization/cleanup
> > +SRCU: Initialization/cleanup::
> > +
> >       DEFINE_SRCU
> >       DEFINE_STATIC_SRCU
> >       init_srcu_struct
> >       cleanup_srcu_struct
> >
> > -All:  lockdep-checked RCU-protected pointer access
> > +All: lockdep-checked RCU-protected pointer access::
> >
> >       rcu_access_pointer
> >       rcu_dereference_raw
> > @@ -976,6 +1003,7 @@ the right tool for your job.
> >
> >
> >  8.  ANSWERS TO QUICK QUIZZES
> > +----------------------------
> >
> >  Quick Quiz #1:       Why is this argument naive?  How could a deadlock
> >               occur when using this algorithm in a real-world Linux
> > --
> > 2.20.1
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/attachments/20191101/678e3afc/attachment-0001.html>

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  3:33   ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
@ 2019-11-01  3:33     ` madhuparnabhowmik04
  2019-11-01  3:33     ` Madhuparna Bhowmik
  2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
  2 siblings, 0 replies; 23+ messages in thread
From: madhuparnabhowmik04 @ 2019-11-01  3:33 UTC (permalink / raw)


On Fri, 1 Nov, 2019, 4:24 AM Paul E. McKenney, <paulmck at kernel.org> wrote:

> On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> > Sync the format with current state of kernel documentation.
> > This change base on rcu-dev branch
> > what changed:
> > - Format bullet lists
> > - Add literal blocks
> >
> > Signed-off-by: Phong Tran <tranmanphong at gmail.com>
>
> Queued and pushed with updated subject line and commit log, thank you!
>
> Could you and Madhuparna please review and test each other's
> .rst-conversion patches?
>

Sure, I will do it.
Regards
Madhuparna


>                                                         Thanx, Paul
>
> > ---
> >  Documentation/RCU/index.rst                   |   1 +
> >  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
> >  2 files changed, 90 insertions(+), 61 deletions(-)
> >  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> >
> > diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> > index 627128c230dc..b9b11481c727 100644
> > --- a/Documentation/RCU/index.rst
> > +++ b/Documentation/RCU/index.rst
> > @@ -8,6 +8,7 @@ RCU concepts
> >     :maxdepth: 3
> >
> >     arrayRCU
> > +   whatisRCU
> >     rcu
> >     listRCU
> >     NMI-RCU
> > diff --git a/Documentation/RCU/whatisRCU.txt
> b/Documentation/RCU/whatisRCU.rst
> > similarity index 91%
> > rename from Documentation/RCU/whatisRCU.txt
> > rename to Documentation/RCU/whatisRCU.rst
> > index 58ba05c4d97f..70d0e4c21917 100644
> > --- a/Documentation/RCU/whatisRCU.txt
> > +++ b/Documentation/RCU/whatisRCU.rst
> > @@ -1,15 +1,18 @@
> > +.. _rcu_doc:
> > +
> >  What is RCU?  --  "Read, Copy, Update"
> > +======================================
> >
> >  Please note that the "What is RCU?" LWN series is an excellent place
> >  to start learning about RCU:
> >
> > -1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > -2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > -3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > -4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > -     2010 Big API Table           http://lwn.net/Articles/419086/
> > -5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > -     2014 Big API Table           http://lwn.net/Articles/609973/
> > +| 1. What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > +| 2. What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > +| 3. RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > +| 4. The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > +|    2010 Big API Table           http://lwn.net/Articles/419086/
> > +| 5. The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > +|    2014 Big API Table           http://lwn.net/Articles/609973/
> >
> >
> >  What is RCU?
> > @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
> >
> >
> >  1.  RCU OVERVIEW
> > +----------------
> >
> >  The basic idea behind RCU is to split updates into "removal" and
> >  "reclamation" phases.  The removal phase removes references to data
> items
> > @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
> >
> >
> >  2.  WHAT IS RCU'S CORE API?
> > +---------------------------
> >
> >  The core RCU API is quite small:
> >
> > @@ -166,7 +171,7 @@ synchronize_rcu()
> >       read-side critical sections on all CPUs have completed.
> >       Note that synchronize_rcu() will -not- necessarily wait for
> >       any subsequent RCU read-side critical sections to complete.
> > -     For example, consider the following sequence of events:
> > +     For example, consider the following sequence of events::
> >
> >                CPU 0                  CPU 1                 CPU 2
> >            ----------------- ------------------------- ---------------
> > @@ -248,13 +253,13 @@ rcu_dereference()
> >
> >       Common coding practice uses rcu_dereference() to copy an
> >       RCU-protected pointer to a local variable, then dereferences
> > -     this local variable, for example as follows:
> > +     this local variable, for example as follows::
> >
> >               p = rcu_dereference(head.next);
> >               return p->data;
> >
> >       However, in this case, one could just as easily combine these
> > -     into one statement:
> > +     into one statement::
> >
> >               return rcu_dereference(head.next)->data;
> >
> > @@ -267,7 +272,7 @@ rcu_dereference()
> >
> >       Note that the value returned by rcu_dereference() is valid
> >       only within the enclosing RCU read-side critical section [1].
> > -     For example, the following is -not- legal:
> > +     For example, the following is -not- legal::
> >
> >               rcu_read_lock();
> >               p = rcu_dereference(head.next);
> > @@ -315,6 +320,7 @@ rcu_dereference()
> >
> >  The following diagram shows how each API communicates among the
> >  reader, updater, and reclaimer.
> > +::
> >
> >
> >           rcu_assign_pointer()
> > @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
> >
> >
> >  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> > +-----------------------------------------------
> >
> >  This section shows a simple use of the core RCU API to protect a
> >  global pointer to a dynamically allocated structure.  More-typical
> >  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> > +::
> >
> >       struct foo {
> >               int a;
> > @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
> >
> >
> >  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> > +--------------------------------------------
> >
> >  In the example above, foo_update_a() blocks until a grace period
> elapses.
> >  This is quite simple, but in some cases one cannot afford to wait so
> >  long -- there might be other high-priority work to be done.
> >
> >  In such cases, one uses call_rcu() rather than synchronize_rcu().
> > -The call_rcu() API is as follows:
> > +The call_rcu() API is as follows::
> >
> >       void call_rcu(struct rcu_head * head,
> >                     void (*func)(struct rcu_head *head));
> > @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
> >  This function invokes func(head) after a grace period has elapsed.
> >  This invocation might happen from either softirq or process context,
> >  so the function is not permitted to block.  The foo struct needs to
> > -have an rcu_head structure added, perhaps as follows:
> > +have an rcu_head structure added, perhaps as follows::
> >
> >       struct foo {
> >               int a;
> > @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
> >               struct rcu_head rcu;
> >       };
> >
> > -The foo_update_a() function might then be written as follows:
> > +The foo_update_a() function might then be written as follows::
> >
> >       /*
> >        * Create a new struct foo that is the same as the one currently
> > @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> follows:
> >               call_rcu(&old_fp->rcu, foo_reclaim);
> >       }
> >
> > -The foo_reclaim() function might appear as follows:
> > +The foo_reclaim() function might appear as follows::
> >
> >       void foo_reclaim(struct rcu_head *rp)
> >       {
> > @@ -552,7 +561,7 @@ o Use call_rcu() -after- removing a data element
> from an
> >
> >  If the callback for call_rcu() is not doing anything more than calling
> >  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> > -to avoid having to write your own callback:
> > +to avoid having to write your own callback::
> >
> >       kfree_rcu(old_fp, rcu);
> >
> > @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> governing the use of RCU.
> >
> >
> >  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> > +------------------------------------------------
> >
> >  One of the nice things about RCU is that it has extremely simple "toy"
> >  implementations that are a good first step towards understanding the
> > @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> deadlock.
> >  However, it is probably the easiest implementation to relate to, so is
> >  a good starting point.
> >
> > -It is extremely simple:
> > +It is extremely simple::
> >
> >       static DEFINE_RWLOCK(rcu_gp_mutex);
> >
> > @@ -614,7 +624,7 @@ It is extremely simple:
> >
> >  [You can ignore rcu_assign_pointer() and rcu_dereference() without
> missing
> >  much.  But here are simplified versions anyway.  And whatever you do,
> > -don't forget about them when submitting patches making use of RCU!]
> > +don't forget about them when submitting patches making use of RCU!]::
> >
> >       #define rcu_assign_pointer(p, v) \
> >       ({ \
> > @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation
> that is based on
> >  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
> >  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
> >  are the same as those shown in the preceding section, so they are
> omitted.
> > +::
> >
> >       void rcu_read_lock(void) { }
> >
> > @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an
> RCU read-side
> >
> >
> >  6.  ANALOGY WITH READER-WRITER LOCKING
> > +--------------------------------------
> >
> >  Although RCU can be used in many different ways, a very common use of
> >  RCU is analogous to reader-writer locking.  The following unified
> >  diff shows how closely related RCU and reader-writer locking can be.
> > +::
> >
> >       @@ -5,5 +5,5 @@ struct el {
> >               int data;
> > @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> locking can be.
> >               return 0;
> >        }
> >
> > -Or, for those who prefer a side-by-side listing:
> > +Or, for those who prefer a side-by-side listing::
> >
> >   1 struct el {                          1 struct el {
> >   2   struct list_head list;             2   struct list_head list;
> > @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
> >   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
> >   9 struct el head;                      9 struct el head;
> >
> > - 1 int search(long key, int *result)    1 int search(long key, int
> *result)
> > - 2 {                                    2 {
> > - 3   struct list_head *lp;              3   struct list_head *lp;
> > - 4   struct el *p;                      4   struct el *p;
> > - 5                                      5
> > - 6   read_lock(&listmutex);             6   rcu_read_lock();
> > - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> > - 8     if (p->key == key) {             8     if (p->key == key) {
> > - 9       *result = p->data;             9       *result = p->data;
> > -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > -11       return 1;                     11       return 1;
> > -12     }                               12     }
> > -13   }                                 13   }
> > -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > -15   return 0;                         15   return 0;
> > -16 }                                   16 }
> > -
> > - 1 int delete(long key)                 1 int delete(long key)
> > - 2 {                                    2 {
> > - 3   struct el *p;                      3   struct el *p;
> > - 4                                      4
> > - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> head, lp) {
> > - 7     if (p->key == key) {             7     if (p->key == key) {
> > - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> > -                                       10       synchronize_rcu();
> > -10       kfree(p);                     11       kfree(p);
> > -11       return 1;                     12       return 1;
> > -12     }                               13     }
> > -13   }                                 14   }
> > -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > -15   return 0;                         16   return 0;
> > -16 }                                   17 }
> > +::
> > +
> > +  1 int search(long key, int *result)    1 int search(long key, int
> *result)
> > +  2 {                                    2 {
> > +  3   struct list_head *lp;              3   struct list_head *lp;
> > +  4   struct el *p;                      4   struct el *p;
> > +  5                                      5
> > +  6   read_lock(&listmutex);             6   rcu_read_lock();
> > +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> > +  8     if (p->key == key) {             8     if (p->key == key) {
> > +  9       *result = p->data;             9       *result = p->data;
> > + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > + 11       return 1;                     11       return 1;
> > + 12     }                               12     }
> > + 13   }                                 13   }
> > + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > + 15   return 0;                         15   return 0;
> > + 16 }                                   16 }
> > +
> > +::
> > +
> > +  1 int delete(long key)                 1 int delete(long key)
> > +  2 {                                    2 {
> > +  3   struct el *p;                      3   struct el *p;
> > +  4                                      4
> > +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> head, lp) {
> > +  7     if (p->key == key) {             7     if (p->key == key) {
> > +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > +  9       write_unlock(&listmutex);      9
>  spin_unlock(&listmutex);
> > +                                        10       synchronize_rcu();
> > + 10       kfree(p);                     11       kfree(p);
> > + 11       return 1;                     12       return 1;
> > + 12     }                               13     }
> > + 13   }                                 14   }
> > + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > + 15   return 0;                         16   return 0;
> > + 16 }                                   17 }
> >
> >  Either way, the differences are quite small.  Read-side locking moves
> >  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> > @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
> >
> >
> >  7.  FULL LIST OF RCU APIs
> > +-------------------------
> >
> >  The RCU APIs are documented in docbook-format header comments in the
> >  Linux-kernel source code, but it helps to have a full list of the
> >  APIs, since there does not appear to be a way to categorize them
> >  in docbook.  Here is the list, by category.
> >
> > -RCU list traversal:
> > +RCU list traversal::
> >
> >       list_entry_rcu
> >       list_first_entry_rcu
> > @@ -854,7 +872,7 @@ RCU list traversal:
> >       hlist_bl_first_rcu
> >       hlist_bl_for_each_entry_rcu
> >
> > -RCU pointer/list update:
> > +RCU pointer/list udate::
> >
> >       rcu_assign_pointer
> >       list_add_rcu
> > @@ -876,7 +894,9 @@ RCU pointer/list update:
> >       hlist_bl_del_rcu
> >       hlist_bl_set_first_rcu
> >
> > -RCU: Critical sections       Grace period            Barrier
> > +RCU::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock           synchronize_net         rcu_barrier
> >       rcu_read_unlock         synchronize_rcu
> > @@ -885,7 +905,9 @@ RCU:      Critical sections       Grace period
>       Barrier
> >       rcu_dereference_check   kfree_rcu
> >       rcu_dereference_protected
> >
> > -bh:  Critical sections       Grace period            Barrier
> > +bh::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock_bh        call_rcu                rcu_barrier
> >       rcu_read_unlock_bh      synchronize_rcu
> > @@ -896,7 +918,9 @@ bh:       Critical sections       Grace period
>       Barrier
> >       rcu_dereference_bh_protected
> >       rcu_read_lock_bh_held
> >
> > -sched:       Critical sections       Grace period            Barrier
> > +sched::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock_sched     call_rcu                rcu_barrier
> >       rcu_read_unlock_sched   synchronize_rcu
> > @@ -910,7 +934,9 @@ sched:    Critical sections       Grace period
>       Barrier
> >       rcu_read_lock_sched_held
> >
> >
> > -SRCU:        Critical sections       Grace period            Barrier
> > +SRCU::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       srcu_read_lock          call_srcu               srcu_barrier
> >       srcu_read_unlock        synchronize_srcu
> > @@ -918,13 +944,14 @@ SRCU:   Critical sections       Grace period
>       Barrier
> >       srcu_dereference_check
> >       srcu_read_lock_held
> >
> > -SRCU:        Initialization/cleanup
> > +SRCU: Initialization/cleanup::
> > +
> >       DEFINE_SRCU
> >       DEFINE_STATIC_SRCU
> >       init_srcu_struct
> >       cleanup_srcu_struct
> >
> > -All:  lockdep-checked RCU-protected pointer access
> > +All: lockdep-checked RCU-protected pointer access::
> >
> >       rcu_access_pointer
> >       rcu_dereference_raw
> > @@ -976,6 +1003,7 @@ the right tool for your job.
> >
> >
> >  8.  ANSWERS TO QUICK QUIZZES
> > +----------------------------
> >
> >  Quick Quiz #1:       Why is this argument naive?  How could a deadlock
> >               occur when using this algorithm in a real-world Linux
> > --
> > 2.20.1
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/attachments/20191101/678e3afc/attachment-0001.html>

^ permalink raw reply	[flat|nested] 23+ messages in thread

* Re: [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  3:33   ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  2019-11-01  3:33     ` madhuparnabhowmik04
@ 2019-11-01  3:33     ` Madhuparna Bhowmik
  2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
  2 siblings, 0 replies; 23+ messages in thread
From: Madhuparna Bhowmik @ 2019-11-01  3:33 UTC (permalink / raw)
  To: paulmck
  Cc: corbet, linux-doc, jiangshanlai, josh, rostedt, linux-kernel,
	rcu, mathieu.desnoyers, joel, linux-kernel-mentees

[-- Attachment #1.1: Type: text/plain, Size: 17989 bytes --]

On Fri, 1 Nov, 2019, 4:24 AM Paul E. McKenney, <paulmck@kernel.org> wrote:

> On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> > Sync the format with current state of kernel documentation.
> > This change base on rcu-dev branch
> > what changed:
> > - Format bullet lists
> > - Add literal blocks
> >
> > Signed-off-by: Phong Tran <tranmanphong@gmail.com>
>
> Queued and pushed with updated subject line and commit log, thank you!
>
> Could you and Madhuparna please review and test each other's
> .rst-conversion patches?
>

Sure, I will do it.
Regards
Madhuparna


>                                                         Thanx, Paul
>
> > ---
> >  Documentation/RCU/index.rst                   |   1 +
> >  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
> >  2 files changed, 90 insertions(+), 61 deletions(-)
> >  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> >
> > diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> > index 627128c230dc..b9b11481c727 100644
> > --- a/Documentation/RCU/index.rst
> > +++ b/Documentation/RCU/index.rst
> > @@ -8,6 +8,7 @@ RCU concepts
> >     :maxdepth: 3
> >
> >     arrayRCU
> > +   whatisRCU
> >     rcu
> >     listRCU
> >     NMI-RCU
> > diff --git a/Documentation/RCU/whatisRCU.txt
> b/Documentation/RCU/whatisRCU.rst
> > similarity index 91%
> > rename from Documentation/RCU/whatisRCU.txt
> > rename to Documentation/RCU/whatisRCU.rst
> > index 58ba05c4d97f..70d0e4c21917 100644
> > --- a/Documentation/RCU/whatisRCU.txt
> > +++ b/Documentation/RCU/whatisRCU.rst
> > @@ -1,15 +1,18 @@
> > +.. _rcu_doc:
> > +
> >  What is RCU?  --  "Read, Copy, Update"
> > +======================================
> >
> >  Please note that the "What is RCU?" LWN series is an excellent place
> >  to start learning about RCU:
> >
> > -1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > -2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > -3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > -4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > -     2010 Big API Table           http://lwn.net/Articles/419086/
> > -5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > -     2014 Big API Table           http://lwn.net/Articles/609973/
> > +| 1. What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > +| 2. What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > +| 3. RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > +| 4. The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > +|    2010 Big API Table           http://lwn.net/Articles/419086/
> > +| 5. The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > +|    2014 Big API Table           http://lwn.net/Articles/609973/
> >
> >
> >  What is RCU?
> > @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
> >
> >
> >  1.  RCU OVERVIEW
> > +----------------
> >
> >  The basic idea behind RCU is to split updates into "removal" and
> >  "reclamation" phases.  The removal phase removes references to data
> items
> > @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
> >
> >
> >  2.  WHAT IS RCU'S CORE API?
> > +---------------------------
> >
> >  The core RCU API is quite small:
> >
> > @@ -166,7 +171,7 @@ synchronize_rcu()
> >       read-side critical sections on all CPUs have completed.
> >       Note that synchronize_rcu() will -not- necessarily wait for
> >       any subsequent RCU read-side critical sections to complete.
> > -     For example, consider the following sequence of events:
> > +     For example, consider the following sequence of events::
> >
> >                CPU 0                  CPU 1                 CPU 2
> >            ----------------- ------------------------- ---------------
> > @@ -248,13 +253,13 @@ rcu_dereference()
> >
> >       Common coding practice uses rcu_dereference() to copy an
> >       RCU-protected pointer to a local variable, then dereferences
> > -     this local variable, for example as follows:
> > +     this local variable, for example as follows::
> >
> >               p = rcu_dereference(head.next);
> >               return p->data;
> >
> >       However, in this case, one could just as easily combine these
> > -     into one statement:
> > +     into one statement::
> >
> >               return rcu_dereference(head.next)->data;
> >
> > @@ -267,7 +272,7 @@ rcu_dereference()
> >
> >       Note that the value returned by rcu_dereference() is valid
> >       only within the enclosing RCU read-side critical section [1].
> > -     For example, the following is -not- legal:
> > +     For example, the following is -not- legal::
> >
> >               rcu_read_lock();
> >               p = rcu_dereference(head.next);
> > @@ -315,6 +320,7 @@ rcu_dereference()
> >
> >  The following diagram shows how each API communicates among the
> >  reader, updater, and reclaimer.
> > +::
> >
> >
> >           rcu_assign_pointer()
> > @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
> >
> >
> >  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> > +-----------------------------------------------
> >
> >  This section shows a simple use of the core RCU API to protect a
> >  global pointer to a dynamically allocated structure.  More-typical
> >  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> > +::
> >
> >       struct foo {
> >               int a;
> > @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
> >
> >
> >  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> > +--------------------------------------------
> >
> >  In the example above, foo_update_a() blocks until a grace period
> elapses.
> >  This is quite simple, but in some cases one cannot afford to wait so
> >  long -- there might be other high-priority work to be done.
> >
> >  In such cases, one uses call_rcu() rather than synchronize_rcu().
> > -The call_rcu() API is as follows:
> > +The call_rcu() API is as follows::
> >
> >       void call_rcu(struct rcu_head * head,
> >                     void (*func)(struct rcu_head *head));
> > @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
> >  This function invokes func(head) after a grace period has elapsed.
> >  This invocation might happen from either softirq or process context,
> >  so the function is not permitted to block.  The foo struct needs to
> > -have an rcu_head structure added, perhaps as follows:
> > +have an rcu_head structure added, perhaps as follows::
> >
> >       struct foo {
> >               int a;
> > @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
> >               struct rcu_head rcu;
> >       };
> >
> > -The foo_update_a() function might then be written as follows:
> > +The foo_update_a() function might then be written as follows::
> >
> >       /*
> >        * Create a new struct foo that is the same as the one currently
> > @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> follows:
> >               call_rcu(&old_fp->rcu, foo_reclaim);
> >       }
> >
> > -The foo_reclaim() function might appear as follows:
> > +The foo_reclaim() function might appear as follows::
> >
> >       void foo_reclaim(struct rcu_head *rp)
> >       {
> > @@ -552,7 +561,7 @@ o Use call_rcu() -after- removing a data element
> from an
> >
> >  If the callback for call_rcu() is not doing anything more than calling
> >  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> > -to avoid having to write your own callback:
> > +to avoid having to write your own callback::
> >
> >       kfree_rcu(old_fp, rcu);
> >
> > @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> governing the use of RCU.
> >
> >
> >  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> > +------------------------------------------------
> >
> >  One of the nice things about RCU is that it has extremely simple "toy"
> >  implementations that are a good first step towards understanding the
> > @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> deadlock.
> >  However, it is probably the easiest implementation to relate to, so is
> >  a good starting point.
> >
> > -It is extremely simple:
> > +It is extremely simple::
> >
> >       static DEFINE_RWLOCK(rcu_gp_mutex);
> >
> > @@ -614,7 +624,7 @@ It is extremely simple:
> >
> >  [You can ignore rcu_assign_pointer() and rcu_dereference() without
> missing
> >  much.  But here are simplified versions anyway.  And whatever you do,
> > -don't forget about them when submitting patches making use of RCU!]
> > +don't forget about them when submitting patches making use of RCU!]::
> >
> >       #define rcu_assign_pointer(p, v) \
> >       ({ \
> > @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation
> that is based on
> >  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
> >  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
> >  are the same as those shown in the preceding section, so they are
> omitted.
> > +::
> >
> >       void rcu_read_lock(void) { }
> >
> > @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an
> RCU read-side
> >
> >
> >  6.  ANALOGY WITH READER-WRITER LOCKING
> > +--------------------------------------
> >
> >  Although RCU can be used in many different ways, a very common use of
> >  RCU is analogous to reader-writer locking.  The following unified
> >  diff shows how closely related RCU and reader-writer locking can be.
> > +::
> >
> >       @@ -5,5 +5,5 @@ struct el {
> >               int data;
> > @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> locking can be.
> >               return 0;
> >        }
> >
> > -Or, for those who prefer a side-by-side listing:
> > +Or, for those who prefer a side-by-side listing::
> >
> >   1 struct el {                          1 struct el {
> >   2   struct list_head list;             2   struct list_head list;
> > @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
> >   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
> >   9 struct el head;                      9 struct el head;
> >
> > - 1 int search(long key, int *result)    1 int search(long key, int
> *result)
> > - 2 {                                    2 {
> > - 3   struct list_head *lp;              3   struct list_head *lp;
> > - 4   struct el *p;                      4   struct el *p;
> > - 5                                      5
> > - 6   read_lock(&listmutex);             6   rcu_read_lock();
> > - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> > - 8     if (p->key == key) {             8     if (p->key == key) {
> > - 9       *result = p->data;             9       *result = p->data;
> > -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > -11       return 1;                     11       return 1;
> > -12     }                               12     }
> > -13   }                                 13   }
> > -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > -15   return 0;                         15   return 0;
> > -16 }                                   16 }
> > -
> > - 1 int delete(long key)                 1 int delete(long key)
> > - 2 {                                    2 {
> > - 3   struct el *p;                      3   struct el *p;
> > - 4                                      4
> > - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> head, lp) {
> > - 7     if (p->key == key) {             7     if (p->key == key) {
> > - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> > -                                       10       synchronize_rcu();
> > -10       kfree(p);                     11       kfree(p);
> > -11       return 1;                     12       return 1;
> > -12     }                               13     }
> > -13   }                                 14   }
> > -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > -15   return 0;                         16   return 0;
> > -16 }                                   17 }
> > +::
> > +
> > +  1 int search(long key, int *result)    1 int search(long key, int
> *result)
> > +  2 {                                    2 {
> > +  3   struct list_head *lp;              3   struct list_head *lp;
> > +  4   struct el *p;                      4   struct el *p;
> > +  5                                      5
> > +  6   read_lock(&listmutex);             6   rcu_read_lock();
> > +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> > +  8     if (p->key == key) {             8     if (p->key == key) {
> > +  9       *result = p->data;             9       *result = p->data;
> > + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > + 11       return 1;                     11       return 1;
> > + 12     }                               12     }
> > + 13   }                                 13   }
> > + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > + 15   return 0;                         15   return 0;
> > + 16 }                                   16 }
> > +
> > +::
> > +
> > +  1 int delete(long key)                 1 int delete(long key)
> > +  2 {                                    2 {
> > +  3   struct el *p;                      3   struct el *p;
> > +  4                                      4
> > +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> head, lp) {
> > +  7     if (p->key == key) {             7     if (p->key == key) {
> > +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > +  9       write_unlock(&listmutex);      9
>  spin_unlock(&listmutex);
> > +                                        10       synchronize_rcu();
> > + 10       kfree(p);                     11       kfree(p);
> > + 11       return 1;                     12       return 1;
> > + 12     }                               13     }
> > + 13   }                                 14   }
> > + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > + 15   return 0;                         16   return 0;
> > + 16 }                                   17 }
> >
> >  Either way, the differences are quite small.  Read-side locking moves
> >  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> > @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
> >
> >
> >  7.  FULL LIST OF RCU APIs
> > +-------------------------
> >
> >  The RCU APIs are documented in docbook-format header comments in the
> >  Linux-kernel source code, but it helps to have a full list of the
> >  APIs, since there does not appear to be a way to categorize them
> >  in docbook.  Here is the list, by category.
> >
> > -RCU list traversal:
> > +RCU list traversal::
> >
> >       list_entry_rcu
> >       list_first_entry_rcu
> > @@ -854,7 +872,7 @@ RCU list traversal:
> >       hlist_bl_first_rcu
> >       hlist_bl_for_each_entry_rcu
> >
> > -RCU pointer/list update:
> > +RCU pointer/list udate::
> >
> >       rcu_assign_pointer
> >       list_add_rcu
> > @@ -876,7 +894,9 @@ RCU pointer/list update:
> >       hlist_bl_del_rcu
> >       hlist_bl_set_first_rcu
> >
> > -RCU: Critical sections       Grace period            Barrier
> > +RCU::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock           synchronize_net         rcu_barrier
> >       rcu_read_unlock         synchronize_rcu
> > @@ -885,7 +905,9 @@ RCU:      Critical sections       Grace period
>       Barrier
> >       rcu_dereference_check   kfree_rcu
> >       rcu_dereference_protected
> >
> > -bh:  Critical sections       Grace period            Barrier
> > +bh::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock_bh        call_rcu                rcu_barrier
> >       rcu_read_unlock_bh      synchronize_rcu
> > @@ -896,7 +918,9 @@ bh:       Critical sections       Grace period
>       Barrier
> >       rcu_dereference_bh_protected
> >       rcu_read_lock_bh_held
> >
> > -sched:       Critical sections       Grace period            Barrier
> > +sched::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       rcu_read_lock_sched     call_rcu                rcu_barrier
> >       rcu_read_unlock_sched   synchronize_rcu
> > @@ -910,7 +934,9 @@ sched:    Critical sections       Grace period
>       Barrier
> >       rcu_read_lock_sched_held
> >
> >
> > -SRCU:        Critical sections       Grace period            Barrier
> > +SRCU::
> > +
> > +     Critical sections       Grace period            Barrier
> >
> >       srcu_read_lock          call_srcu               srcu_barrier
> >       srcu_read_unlock        synchronize_srcu
> > @@ -918,13 +944,14 @@ SRCU:   Critical sections       Grace period
>       Barrier
> >       srcu_dereference_check
> >       srcu_read_lock_held
> >
> > -SRCU:        Initialization/cleanup
> > +SRCU: Initialization/cleanup::
> > +
> >       DEFINE_SRCU
> >       DEFINE_STATIC_SRCU
> >       init_srcu_struct
> >       cleanup_srcu_struct
> >
> > -All:  lockdep-checked RCU-protected pointer access
> > +All: lockdep-checked RCU-protected pointer access::
> >
> >       rcu_access_pointer
> >       rcu_dereference_raw
> > @@ -976,6 +1003,7 @@ the right tool for your job.
> >
> >
> >  8.  ANSWERS TO QUICK QUIZZES
> > +----------------------------
> >
> >  Quick Quiz #1:       Why is this argument naive?  How could a deadlock
> >               occur when using this algorithm in a real-world Linux
> > --
> > 2.20.1
> >
>

[-- Attachment #1.2: Type: text/html, Size: 24707 bytes --]

<div dir="auto"><div><br><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, 1 Nov, 2019, 4:24 AM Paul E. McKenney, &lt;<a href="mailto:paulmck@kernel.org">paulmck@kernel.org</a>&gt; wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:<br>
&gt; Sync the format with current state of kernel documentation.<br>
&gt; This change base on rcu-dev branch<br>
&gt; what changed:<br>
&gt; - Format bullet lists<br>
&gt; - Add literal blocks<br>
&gt; <br>
&gt; Signed-off-by: Phong Tran &lt;<a href="mailto:tranmanphong@gmail.com" target="_blank" rel="noreferrer">tranmanphong@gmail.com</a>&gt;<br>
<br>
Queued and pushed with updated subject line and commit log, thank you!<br>
<br>
Could you and Madhuparna please review and test each other&#39;s<br>
.rst-conversion patches?<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">Sure, I will do it. </div><div dir="auto">Regards </div><div dir="auto">Madhuparna </div><div dir="auto"><br></div><div dir="auto"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
                                                        Thanx, Paul<br>
<br>
&gt; ---<br>
&gt;  Documentation/RCU/index.rst                   |   1 +<br>
&gt;  .../RCU/{whatisRCU.txt =&gt; whatisRCU.rst}      | 150 +++++++++++-------<br>
&gt;  2 files changed, 90 insertions(+), 61 deletions(-)<br>
&gt;  rename Documentation/RCU/{whatisRCU.txt =&gt; whatisRCU.rst} (91%)<br>
&gt; <br>
&gt; diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst<br>
&gt; index 627128c230dc..b9b11481c727 100644<br>
&gt; --- a/Documentation/RCU/index.rst<br>
&gt; +++ b/Documentation/RCU/index.rst<br>
&gt; @@ -8,6 +8,7 @@ RCU concepts<br>
&gt;     :maxdepth: 3<br>
&gt;  <br>
&gt;     arrayRCU<br>
&gt; +   whatisRCU<br>
&gt;     rcu<br>
&gt;     listRCU<br>
&gt;     NMI-RCU<br>
&gt; diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst<br>
&gt; similarity index 91%<br>
&gt; rename from Documentation/RCU/whatisRCU.txt<br>
&gt; rename to Documentation/RCU/whatisRCU.rst<br>
&gt; index 58ba05c4d97f..70d0e4c21917 100644<br>
&gt; --- a/Documentation/RCU/whatisRCU.txt<br>
&gt; +++ b/Documentation/RCU/whatisRCU.rst<br>
&gt; @@ -1,15 +1,18 @@<br>
&gt; +.. _rcu_doc:<br>
&gt; +<br>
&gt;  What is RCU?  --  &quot;Read, Copy, Update&quot;<br>
&gt; +======================================<br>
&gt;  <br>
&gt;  Please note that the &quot;What is RCU?&quot; LWN series is an excellent place<br>
&gt;  to start learning about RCU:<br>
&gt;  <br>
&gt; -1.   What is RCU, Fundamentally?  <a href="http://lwn.net/Articles/262464/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/262464/</a><br>
&gt; -2.   What is RCU? Part 2: Usage   <a href="http://lwn.net/Articles/263130/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/263130/</a><br>
&gt; -3.   RCU part 3: the RCU API      <a href="http://lwn.net/Articles/264090/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/264090/</a><br>
&gt; -4.   The RCU API, 2010 Edition    <a href="http://lwn.net/Articles/418853/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/418853/</a><br>
&gt; -     2010 Big API Table           <a href="http://lwn.net/Articles/419086/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/419086/</a><br>
&gt; -5.   The RCU API, 2014 Edition    <a href="http://lwn.net/Articles/609904/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/609904/</a><br>
&gt; -     2014 Big API Table           <a href="http://lwn.net/Articles/609973/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/609973/</a><br>
&gt; +| 1. What is RCU, Fundamentally?  <a href="http://lwn.net/Articles/262464/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/262464/</a><br>
&gt; +| 2. What is RCU? Part 2: Usage   <a href="http://lwn.net/Articles/263130/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/263130/</a><br>
&gt; +| 3. RCU part 3: the RCU API      <a href="http://lwn.net/Articles/264090/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/264090/</a><br>
&gt; +| 4. The RCU API, 2010 Edition    <a href="http://lwn.net/Articles/418853/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/418853/</a><br>
&gt; +|    2010 Big API Table           <a href="http://lwn.net/Articles/419086/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/419086/</a><br>
&gt; +| 5. The RCU API, 2014 Edition    <a href="http://lwn.net/Articles/609904/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/609904/</a><br>
&gt; +|    2014 Big API Table           <a href="http://lwn.net/Articles/609973/" rel="noreferrer noreferrer" target="_blank">http://lwn.net/Articles/609973/</a><br>
&gt;  <br>
&gt;  <br>
&gt;  What is RCU?<br>
&gt; @@ -51,6 +54,7 @@ never need this document anyway.  ;-)<br>
&gt;  <br>
&gt;  <br>
&gt;  1.  RCU OVERVIEW<br>
&gt; +----------------<br>
&gt;  <br>
&gt;  The basic idea behind RCU is to split updates into &quot;removal&quot; and<br>
&gt;  &quot;reclamation&quot; phases.  The removal phase removes references to data items<br>
&gt; @@ -118,6 +122,7 @@ Read on to learn about how RCU&#39;s API makes this easy.<br>
&gt;  <br>
&gt;  <br>
&gt;  2.  WHAT IS RCU&#39;S CORE API?<br>
&gt; +---------------------------<br>
&gt;  <br>
&gt;  The core RCU API is quite small:<br>
&gt;  <br>
&gt; @@ -166,7 +171,7 @@ synchronize_rcu()<br>
&gt;       read-side critical sections on all CPUs have completed.<br>
&gt;       Note that synchronize_rcu() will -not- necessarily wait for<br>
&gt;       any subsequent RCU read-side critical sections to complete.<br>
&gt; -     For example, consider the following sequence of events:<br>
&gt; +     For example, consider the following sequence of events::<br>
&gt;  <br>
&gt;                CPU 0                  CPU 1                 CPU 2<br>
&gt;            ----------------- ------------------------- ---------------<br>
&gt; @@ -248,13 +253,13 @@ rcu_dereference()<br>
&gt;  <br>
&gt;       Common coding practice uses rcu_dereference() to copy an<br>
&gt;       RCU-protected pointer to a local variable, then dereferences<br>
&gt; -     this local variable, for example as follows:<br>
&gt; +     this local variable, for example as follows::<br>
&gt;  <br>
&gt;               p = rcu_dereference(head.next);<br>
&gt;               return p-&gt;data;<br>
&gt;  <br>
&gt;       However, in this case, one could just as easily combine these<br>
&gt; -     into one statement:<br>
&gt; +     into one statement::<br>
&gt;  <br>
&gt;               return rcu_dereference(head.next)-&gt;data;<br>
&gt;  <br>
&gt; @@ -267,7 +272,7 @@ rcu_dereference()<br>
&gt;  <br>
&gt;       Note that the value returned by rcu_dereference() is valid<br>
&gt;       only within the enclosing RCU read-side critical section [1].<br>
&gt; -     For example, the following is -not- legal:<br>
&gt; +     For example, the following is -not- legal::<br>
&gt;  <br>
&gt;               rcu_read_lock();<br>
&gt;               p = rcu_dereference(head.next);<br>
&gt; @@ -315,6 +320,7 @@ rcu_dereference()<br>
&gt;  <br>
&gt;  The following diagram shows how each API communicates among the<br>
&gt;  reader, updater, and reclaimer.<br>
&gt; +::<br>
&gt;  <br>
&gt;  <br>
&gt;           rcu_assign_pointer()<br>
&gt; @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.<br>
&gt;  <br>
&gt;  <br>
&gt;  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?<br>
&gt; +-----------------------------------------------<br>
&gt;  <br>
&gt;  This section shows a simple use of the core RCU API to protect a<br>
&gt;  global pointer to a dynamically allocated structure.  More-typical<br>
&gt;  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.<br>
&gt; +::<br>
&gt;  <br>
&gt;       struct foo {<br>
&gt;               int a;<br>
&gt; @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.<br>
&gt;  <br>
&gt;  <br>
&gt;  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?<br>
&gt; +--------------------------------------------<br>
&gt;  <br>
&gt;  In the example above, foo_update_a() blocks until a grace period elapses.<br>
&gt;  This is quite simple, but in some cases one cannot afford to wait so<br>
&gt;  long -- there might be other high-priority work to be done.<br>
&gt;  <br>
&gt;  In such cases, one uses call_rcu() rather than synchronize_rcu().<br>
&gt; -The call_rcu() API is as follows:<br>
&gt; +The call_rcu() API is as follows::<br>
&gt;  <br>
&gt;       void call_rcu(struct rcu_head * head,<br>
&gt;                     void (*func)(struct rcu_head *head));<br>
&gt; @@ -481,7 +490,7 @@ The call_rcu() API is as follows:<br>
&gt;  This function invokes func(head) after a grace period has elapsed.<br>
&gt;  This invocation might happen from either softirq or process context,<br>
&gt;  so the function is not permitted to block.  The foo struct needs to<br>
&gt; -have an rcu_head structure added, perhaps as follows:<br>
&gt; +have an rcu_head structure added, perhaps as follows::<br>
&gt;  <br>
&gt;       struct foo {<br>
&gt;               int a;<br>
&gt; @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:<br>
&gt;               struct rcu_head rcu;<br>
&gt;       };<br>
&gt;  <br>
&gt; -The foo_update_a() function might then be written as follows:<br>
&gt; +The foo_update_a() function might then be written as follows::<br>
&gt;  <br>
&gt;       /*<br>
&gt;        * Create a new struct foo that is the same as the one currently<br>
&gt; @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as follows:<br>
&gt;               call_rcu(&amp;old_fp-&gt;rcu, foo_reclaim);<br>
&gt;       }<br>
&gt;  <br>
&gt; -The foo_reclaim() function might appear as follows:<br>
&gt; +The foo_reclaim() function might appear as follows::<br>
&gt;  <br>
&gt;       void foo_reclaim(struct rcu_head *rp)<br>
&gt;       {<br>
&gt; @@ -552,7 +561,7 @@ o Use call_rcu() -after- removing a data element from an<br>
&gt;  <br>
&gt;  If the callback for call_rcu() is not doing anything more than calling<br>
&gt;  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()<br>
&gt; -to avoid having to write your own callback:<br>
&gt; +to avoid having to write your own callback::<br>
&gt;  <br>
&gt;       kfree_rcu(old_fp, rcu);<br>
&gt;  <br>
&gt; @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules governing the use of RCU.<br>
&gt;  <br>
&gt;  <br>
&gt;  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?<br>
&gt; +------------------------------------------------<br>
&gt;  <br>
&gt;  One of the nice things about RCU is that it has extremely simple &quot;toy&quot;<br>
&gt;  implementations that are a good first step towards understanding the<br>
&gt; @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can deadlock.<br>
&gt;  However, it is probably the easiest implementation to relate to, so is<br>
&gt;  a good starting point.<br>
&gt;  <br>
&gt; -It is extremely simple:<br>
&gt; +It is extremely simple::<br>
&gt;  <br>
&gt;       static DEFINE_RWLOCK(rcu_gp_mutex);<br>
&gt;  <br>
&gt; @@ -614,7 +624,7 @@ It is extremely simple:<br>
&gt;  <br>
&gt;  [You can ignore rcu_assign_pointer() and rcu_dereference() without missing<br>
&gt;  much.  But here are simplified versions anyway.  And whatever you do,<br>
&gt; -don&#39;t forget about them when submitting patches making use of RCU!]<br>
&gt; +don&#39;t forget about them when submitting patches making use of RCU!]::<br>
&gt;  <br>
&gt;       #define rcu_assign_pointer(p, v) \<br>
&gt;       ({ \<br>
&gt; @@ -659,6 +669,7 @@ This section presents a &quot;toy&quot; RCU implementation that is based on<br>
&gt;  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT<br>
&gt;  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()<br>
&gt;  are the same as those shown in the preceding section, so they are omitted.<br>
&gt; +::<br>
&gt;  <br>
&gt;       void rcu_read_lock(void) { }<br>
&gt;  <br>
&gt; @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU read-side<br>
&gt;  <br>
&gt;  <br>
&gt;  6.  ANALOGY WITH READER-WRITER LOCKING<br>
&gt; +--------------------------------------<br>
&gt;  <br>
&gt;  Although RCU can be used in many different ways, a very common use of<br>
&gt;  RCU is analogous to reader-writer locking.  The following unified<br>
&gt;  diff shows how closely related RCU and reader-writer locking can be.<br>
&gt; +::<br>
&gt;  <br>
&gt;       @@ -5,5 +5,5 @@ struct el {<br>
&gt;               int data;<br>
&gt; @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer locking can be.<br>
&gt;               return 0;<br>
&gt;        }<br>
&gt;  <br>
&gt; -Or, for those who prefer a side-by-side listing:<br>
&gt; +Or, for those who prefer a side-by-side listing::<br>
&gt;  <br>
&gt;   1 struct el {                          1 struct el {<br>
&gt;   2   struct list_head list;             2   struct list_head list;<br>
&gt; @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:<br>
&gt;   8 rwlock_t listmutex;                  8 spinlock_t listmutex;<br>
&gt;   9 struct el head;                      9 struct el head;<br>
&gt;  <br>
&gt; - 1 int search(long key, int *result)    1 int search(long key, int *result)<br>
&gt; - 2 {                                    2 {<br>
&gt; - 3   struct list_head *lp;              3   struct list_head *lp;<br>
&gt; - 4   struct el *p;                      4   struct el *p;<br>
&gt; - 5                                      5<br>
&gt; - 6   read_lock(&amp;listmutex);             6   rcu_read_lock();<br>
&gt; - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {<br>
&gt; - 8     if (p-&gt;key == key) {             8     if (p-&gt;key == key) {<br>
&gt; - 9       *result = p-&gt;data;             9       *result = p-&gt;data;<br>
&gt; -10       read_unlock(&amp;listmutex);      10       rcu_read_unlock();<br>
&gt; -11       return 1;                     11       return 1;<br>
&gt; -12     }                               12     }<br>
&gt; -13   }                                 13   }<br>
&gt; -14   read_unlock(&amp;listmutex);          14   rcu_read_unlock();<br>
&gt; -15   return 0;                         15   return 0;<br>
&gt; -16 }                                   16 }<br>
&gt; -<br>
&gt; - 1 int delete(long key)                 1 int delete(long key)<br>
&gt; - 2 {                                    2 {<br>
&gt; - 3   struct el *p;                      3   struct el *p;<br>
&gt; - 4                                      4<br>
&gt; - 5   write_lock(&amp;listmutex);            5   spin_lock(&amp;listmutex);<br>
&gt; - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {<br>
&gt; - 7     if (p-&gt;key == key) {             7     if (p-&gt;key == key) {<br>
&gt; - 8       list_del(&amp;p-&gt;list);            8       list_del_rcu(&amp;p-&gt;list);<br>
&gt; - 9       write_unlock(&amp;listmutex);      9       spin_unlock(&amp;listmutex);<br>
&gt; -                                       10       synchronize_rcu();<br>
&gt; -10       kfree(p);                     11       kfree(p);<br>
&gt; -11       return 1;                     12       return 1;<br>
&gt; -12     }                               13     }<br>
&gt; -13   }                                 14   }<br>
&gt; -14   write_unlock(&amp;listmutex);         15   spin_unlock(&amp;listmutex);<br>
&gt; -15   return 0;                         16   return 0;<br>
&gt; -16 }                                   17 }<br>
&gt; +::<br>
&gt; +<br>
&gt; +  1 int search(long key, int *result)    1 int search(long key, int *result)<br>
&gt; +  2 {                                    2 {<br>
&gt; +  3   struct list_head *lp;              3   struct list_head *lp;<br>
&gt; +  4   struct el *p;                      4   struct el *p;<br>
&gt; +  5                                      5<br>
&gt; +  6   read_lock(&amp;listmutex);             6   rcu_read_lock();<br>
&gt; +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {<br>
&gt; +  8     if (p-&gt;key == key) {             8     if (p-&gt;key == key) {<br>
&gt; +  9       *result = p-&gt;data;             9       *result = p-&gt;data;<br>
&gt; + 10       read_unlock(&amp;listmutex);      10       rcu_read_unlock();<br>
&gt; + 11       return 1;                     11       return 1;<br>
&gt; + 12     }                               12     }<br>
&gt; + 13   }                                 13   }<br>
&gt; + 14   read_unlock(&amp;listmutex);          14   rcu_read_unlock();<br>
&gt; + 15   return 0;                         15   return 0;<br>
&gt; + 16 }                                   16 }<br>
&gt; +<br>
&gt; +::<br>
&gt; +<br>
&gt; +  1 int delete(long key)                 1 int delete(long key)<br>
&gt; +  2 {                                    2 {<br>
&gt; +  3   struct el *p;                      3   struct el *p;<br>
&gt; +  4                                      4<br>
&gt; +  5   write_lock(&amp;listmutex);            5   spin_lock(&amp;listmutex);<br>
&gt; +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {<br>
&gt; +  7     if (p-&gt;key == key) {             7     if (p-&gt;key == key) {<br>
&gt; +  8       list_del(&amp;p-&gt;list);            8       list_del_rcu(&amp;p-&gt;list);<br>
&gt; +  9       write_unlock(&amp;listmutex);      9       spin_unlock(&amp;listmutex);<br>
&gt; +                                        10       synchronize_rcu();<br>
&gt; + 10       kfree(p);                     11       kfree(p);<br>
&gt; + 11       return 1;                     12       return 1;<br>
&gt; + 12     }                               13     }<br>
&gt; + 13   }                                 14   }<br>
&gt; + 14   write_unlock(&amp;listmutex);         15   spin_unlock(&amp;listmutex);<br>
&gt; + 15   return 0;                         16   return 0;<br>
&gt; + 16 }                                   17 }<br>
&gt;  <br>
&gt;  Either way, the differences are quite small.  Read-side locking moves<br>
&gt;  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from<br>
&gt; @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().<br>
&gt;  <br>
&gt;  <br>
&gt;  7.  FULL LIST OF RCU APIs<br>
&gt; +-------------------------<br>
&gt;  <br>
&gt;  The RCU APIs are documented in docbook-format header comments in the<br>
&gt;  Linux-kernel source code, but it helps to have a full list of the<br>
&gt;  APIs, since there does not appear to be a way to categorize them<br>
&gt;  in docbook.  Here is the list, by category.<br>
&gt;  <br>
&gt; -RCU list traversal:<br>
&gt; +RCU list traversal::<br>
&gt;  <br>
&gt;       list_entry_rcu<br>
&gt;       list_first_entry_rcu<br>
&gt; @@ -854,7 +872,7 @@ RCU list traversal:<br>
&gt;       hlist_bl_first_rcu<br>
&gt;       hlist_bl_for_each_entry_rcu<br>
&gt;  <br>
&gt; -RCU pointer/list update:<br>
&gt; +RCU pointer/list udate::<br>
&gt;  <br>
&gt;       rcu_assign_pointer<br>
&gt;       list_add_rcu<br>
&gt; @@ -876,7 +894,9 @@ RCU pointer/list update:<br>
&gt;       hlist_bl_del_rcu<br>
&gt;       hlist_bl_set_first_rcu<br>
&gt;  <br>
&gt; -RCU: Critical sections       Grace period            Barrier<br>
&gt; +RCU::<br>
&gt; +<br>
&gt; +     Critical sections       Grace period            Barrier<br>
&gt;  <br>
&gt;       rcu_read_lock           synchronize_net         rcu_barrier<br>
&gt;       rcu_read_unlock         synchronize_rcu<br>
&gt; @@ -885,7 +905,9 @@ RCU:      Critical sections       Grace period            Barrier<br>
&gt;       rcu_dereference_check   kfree_rcu<br>
&gt;       rcu_dereference_protected<br>
&gt;  <br>
&gt; -bh:  Critical sections       Grace period            Barrier<br>
&gt; +bh::<br>
&gt; +<br>
&gt; +     Critical sections       Grace period            Barrier<br>
&gt;  <br>
&gt;       rcu_read_lock_bh        call_rcu                rcu_barrier<br>
&gt;       rcu_read_unlock_bh      synchronize_rcu<br>
&gt; @@ -896,7 +918,9 @@ bh:       Critical sections       Grace period            Barrier<br>
&gt;       rcu_dereference_bh_protected<br>
&gt;       rcu_read_lock_bh_held<br>
&gt;  <br>
&gt; -sched:       Critical sections       Grace period            Barrier<br>
&gt; +sched::<br>
&gt; +<br>
&gt; +     Critical sections       Grace period            Barrier<br>
&gt;  <br>
&gt;       rcu_read_lock_sched     call_rcu                rcu_barrier<br>
&gt;       rcu_read_unlock_sched   synchronize_rcu<br>
&gt; @@ -910,7 +934,9 @@ sched:    Critical sections       Grace period            Barrier<br>
&gt;       rcu_read_lock_sched_held<br>
&gt;  <br>
&gt;  <br>
&gt; -SRCU:        Critical sections       Grace period            Barrier<br>
&gt; +SRCU::<br>
&gt; +<br>
&gt; +     Critical sections       Grace period            Barrier<br>
&gt;  <br>
&gt;       srcu_read_lock          call_srcu               srcu_barrier<br>
&gt;       srcu_read_unlock        synchronize_srcu<br>
&gt; @@ -918,13 +944,14 @@ SRCU:   Critical sections       Grace period            Barrier<br>
&gt;       srcu_dereference_check<br>
&gt;       srcu_read_lock_held<br>
&gt;  <br>
&gt; -SRCU:        Initialization/cleanup<br>
&gt; +SRCU: Initialization/cleanup::<br>
&gt; +<br>
&gt;       DEFINE_SRCU<br>
&gt;       DEFINE_STATIC_SRCU<br>
&gt;       init_srcu_struct<br>
&gt;       cleanup_srcu_struct<br>
&gt;  <br>
&gt; -All:  lockdep-checked RCU-protected pointer access<br>
&gt; +All: lockdep-checked RCU-protected pointer access::<br>
&gt;  <br>
&gt;       rcu_access_pointer<br>
&gt;       rcu_dereference_raw<br>
&gt; @@ -976,6 +1003,7 @@ the right tool for your job.<br>
&gt;  <br>
&gt;  <br>
&gt;  8.  ANSWERS TO QUICK QUIZZES<br>
&gt; +----------------------------<br>
&gt;  <br>
&gt;  Quick Quiz #1:       Why is this argument naive?  How could a deadlock<br>
&gt;               occur when using this algorithm in a real-world Linux<br>
&gt; -- <br>
&gt; 2.20.1<br>
&gt; <br>
</blockquote></div></div></div>

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  1:17   ` tranmanphong at gmail.com (Phong Tran)
  2019-11-01  1:17     ` Phong Tran
  2019-11-01  1:17     ` tranmanphong
@ 2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
  2019-11-01  7:53       ` paulmck
  2019-11-01  7:53       ` Paul E. McKenney
  2 siblings, 2 replies; 23+ messages in thread
From: paulmck at kernel.org (Paul E. McKenney) @ 2019-11-01  7:53 UTC (permalink / raw)


On Fri, Nov 01, 2019 at 08:17:36AM +0700, Phong Tran wrote:
> Hi Paul,
> On 11/1/19 5:54 AM, Paul E. McKenney wrote:
> > Could you and Madhuparna please review and test each other's
> > .rst-conversion patches?
> 
> It's fine.
> pull and "make SPHINXDIRS="RCU" htmldocs pdfdocs" rcu dev branch
> without error or warning.

Very good, thank you!

Once you have done that (or if you have already done that) and have
verified that the resulting .html and .pdf files for the changed portions
look good, you can respond with a Tested-by tag, which has "Tested-by:",
your name, and your email within "<" and ">".  For example, commit
127068abe85b ("i2c: qcom-geni: Disable DMA processing on the Lenovo Yoga
C630") has this:

Tested-by: Bjorn Andersson <bjorn.andersson at linaro.org>

After you review the code, for example, by checking either the patch or the
resulting .rst file, you can respond with a very similar Reviewed-by tag.
Which allows you to get a start on participating in the code-review
process.

							Thanx, Paul

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
@ 2019-11-01  7:53       ` paulmck
  2019-11-01  7:53       ` Paul E. McKenney
  1 sibling, 0 replies; 23+ messages in thread
From: paulmck @ 2019-11-01  7:53 UTC (permalink / raw)


On Fri, Nov 01, 2019 at 08:17:36AM +0700, Phong Tran wrote:
> Hi Paul,
> On 11/1/19 5:54 AM, Paul E. McKenney wrote:
> > Could you and Madhuparna please review and test each other's
> > .rst-conversion patches?
> 
> It's fine.
> pull and "make SPHINXDIRS="RCU" htmldocs pdfdocs" rcu dev branch
> without error or warning.

Very good, thank you!

Once you have done that (or if you have already done that) and have
verified that the resulting .html and .pdf files for the changed portions
look good, you can respond with a Tested-by tag, which has "Tested-by:",
your name, and your email within "<" and ">".  For example, commit
127068abe85b ("i2c: qcom-geni: Disable DMA processing on the Lenovo Yoga
C630") has this:

Tested-by: Bjorn Andersson <bjorn.andersson at linaro.org>

After you review the code, for example, by checking either the patch or the
resulting .rst file, you can respond with a very similar Reviewed-by tag.
Which allows you to get a start on participating in the code-review
process.

							Thanx, Paul

^ permalink raw reply	[flat|nested] 23+ messages in thread

* Re: [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
  2019-11-01  7:53       ` paulmck
@ 2019-11-01  7:53       ` Paul E. McKenney
  1 sibling, 0 replies; 23+ messages in thread
From: Paul E. McKenney @ 2019-11-01  7:53 UTC (permalink / raw)
  To: Phong Tran
  Cc: corbet, linux-doc, jiangshanlai, josh, rostedt, linux-kernel,
	rcu, mathieu.desnoyers, joel, linux-kernel-mentees

On Fri, Nov 01, 2019 at 08:17:36AM +0700, Phong Tran wrote:
> Hi Paul,
> On 11/1/19 5:54 AM, Paul E. McKenney wrote:
> > Could you and Madhuparna please review and test each other's
> > .rst-conversion patches?
> 
> It's fine.
> pull and "make SPHINXDIRS="RCU" htmldocs pdfdocs" rcu dev branch
> without error or warning.

Very good, thank you!

Once you have done that (or if you have already done that) and have
verified that the resulting .html and .pdf files for the changed portions
look good, you can respond with a Tested-by tag, which has "Tested-by:",
your name, and your email within "<" and ">".  For example, commit
127068abe85b ("i2c: qcom-geni: Disable DMA processing on the Lenovo Yoga
C630") has this:

Tested-by: Bjorn Andersson <bjorn.andersson@linaro.org>

After you review the code, for example, by checking either the patch or the
resulting .rst file, you can respond with a very similar Reviewed-by tag.
Which allows you to get a start on participating in the code-review
process.

							Thanx, Paul
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  3:33   ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  2019-11-01  3:33     ` madhuparnabhowmik04
  2019-11-01  3:33     ` Madhuparna Bhowmik
@ 2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
  2019-11-01  7:53       ` paulmck
  2019-11-01  7:53       ` Paul E. McKenney
  2 siblings, 2 replies; 23+ messages in thread
From: paulmck at kernel.org (Paul E. McKenney) @ 2019-11-01  7:53 UTC (permalink / raw)


On Fri, Nov 01, 2019 at 09:03:57AM +0530, Madhuparna Bhowmik wrote:
> On Fri, 1 Nov, 2019, 4:24 AM Paul E. McKenney, <paulmck at kernel.org> wrote:
> 
> > On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> > > Sync the format with current state of kernel documentation.
> > > This change base on rcu-dev branch
> > > what changed:
> > > - Format bullet lists
> > > - Add literal blocks
> > >
> > > Signed-off-by: Phong Tran <tranmanphong at gmail.com>
> >
> > Queued and pushed with updated subject line and commit log, thank you!
> >
> > Could you and Madhuparna please review and test each other's
> > .rst-conversion patches?
> >
> 
> Sure, I will do it.

Thank you, Madhuparna!

							Thanx, Paul

> Regards
> Madhuparna
> 
> 
> >                                                         Thanx, Paul
> >
> > > ---
> > >  Documentation/RCU/index.rst                   |   1 +
> > >  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
> > >  2 files changed, 90 insertions(+), 61 deletions(-)
> > >  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> > >
> > > diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> > > index 627128c230dc..b9b11481c727 100644
> > > --- a/Documentation/RCU/index.rst
> > > +++ b/Documentation/RCU/index.rst
> > > @@ -8,6 +8,7 @@ RCU concepts
> > >     :maxdepth: 3
> > >
> > >     arrayRCU
> > > +   whatisRCU
> > >     rcu
> > >     listRCU
> > >     NMI-RCU
> > > diff --git a/Documentation/RCU/whatisRCU.txt
> > b/Documentation/RCU/whatisRCU.rst
> > > similarity index 91%
> > > rename from Documentation/RCU/whatisRCU.txt
> > > rename to Documentation/RCU/whatisRCU.rst
> > > index 58ba05c4d97f..70d0e4c21917 100644
> > > --- a/Documentation/RCU/whatisRCU.txt
> > > +++ b/Documentation/RCU/whatisRCU.rst
> > > @@ -1,15 +1,18 @@
> > > +.. _rcu_doc:
> > > +
> > >  What is RCU?  --  "Read, Copy, Update"
> > > +======================================
> > >
> > >  Please note that the "What is RCU?" LWN series is an excellent place
> > >  to start learning about RCU:
> > >
> > > -1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > > -2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > > -3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > > -4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > > -     2010 Big API Table           http://lwn.net/Articles/419086/
> > > -5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > > -     2014 Big API Table           http://lwn.net/Articles/609973/
> > > +| 1. What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > > +| 2. What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > > +| 3. RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > > +| 4. The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > > +|    2010 Big API Table           http://lwn.net/Articles/419086/
> > > +| 5. The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > > +|    2014 Big API Table           http://lwn.net/Articles/609973/
> > >
> > >
> > >  What is RCU?
> > > @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
> > >
> > >
> > >  1.  RCU OVERVIEW
> > > +----------------
> > >
> > >  The basic idea behind RCU is to split updates into "removal" and
> > >  "reclamation" phases.  The removal phase removes references to data
> > items
> > > @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
> > >
> > >
> > >  2.  WHAT IS RCU'S CORE API?
> > > +---------------------------
> > >
> > >  The core RCU API is quite small:
> > >
> > > @@ -166,7 +171,7 @@ synchronize_rcu()
> > >       read-side critical sections on all CPUs have completed.
> > >       Note that synchronize_rcu() will -not- necessarily wait for
> > >       any subsequent RCU read-side critical sections to complete.
> > > -     For example, consider the following sequence of events:
> > > +     For example, consider the following sequence of events::
> > >
> > >                CPU 0                  CPU 1                 CPU 2
> > >            ----------------- ------------------------- ---------------
> > > @@ -248,13 +253,13 @@ rcu_dereference()
> > >
> > >       Common coding practice uses rcu_dereference() to copy an
> > >       RCU-protected pointer to a local variable, then dereferences
> > > -     this local variable, for example as follows:
> > > +     this local variable, for example as follows::
> > >
> > >               p = rcu_dereference(head.next);
> > >               return p->data;
> > >
> > >       However, in this case, one could just as easily combine these
> > > -     into one statement:
> > > +     into one statement::
> > >
> > >               return rcu_dereference(head.next)->data;
> > >
> > > @@ -267,7 +272,7 @@ rcu_dereference()
> > >
> > >       Note that the value returned by rcu_dereference() is valid
> > >       only within the enclosing RCU read-side critical section [1].
> > > -     For example, the following is -not- legal:
> > > +     For example, the following is -not- legal::
> > >
> > >               rcu_read_lock();
> > >               p = rcu_dereference(head.next);
> > > @@ -315,6 +320,7 @@ rcu_dereference()
> > >
> > >  The following diagram shows how each API communicates among the
> > >  reader, updater, and reclaimer.
> > > +::
> > >
> > >
> > >           rcu_assign_pointer()
> > > @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
> > >
> > >
> > >  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> > > +-----------------------------------------------
> > >
> > >  This section shows a simple use of the core RCU API to protect a
> > >  global pointer to a dynamically allocated structure.  More-typical
> > >  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> > > +::
> > >
> > >       struct foo {
> > >               int a;
> > > @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
> > >
> > >
> > >  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> > > +--------------------------------------------
> > >
> > >  In the example above, foo_update_a() blocks until a grace period
> > elapses.
> > >  This is quite simple, but in some cases one cannot afford to wait so
> > >  long -- there might be other high-priority work to be done.
> > >
> > >  In such cases, one uses call_rcu() rather than synchronize_rcu().
> > > -The call_rcu() API is as follows:
> > > +The call_rcu() API is as follows::
> > >
> > >       void call_rcu(struct rcu_head * head,
> > >                     void (*func)(struct rcu_head *head));
> > > @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
> > >  This function invokes func(head) after a grace period has elapsed.
> > >  This invocation might happen from either softirq or process context,
> > >  so the function is not permitted to block.  The foo struct needs to
> > > -have an rcu_head structure added, perhaps as follows:
> > > +have an rcu_head structure added, perhaps as follows::
> > >
> > >       struct foo {
> > >               int a;
> > > @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
> > >               struct rcu_head rcu;
> > >       };
> > >
> > > -The foo_update_a() function might then be written as follows:
> > > +The foo_update_a() function might then be written as follows::
> > >
> > >       /*
> > >        * Create a new struct foo that is the same as the one currently
> > > @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> > follows:
> > >               call_rcu(&old_fp->rcu, foo_reclaim);
> > >       }
> > >
> > > -The foo_reclaim() function might appear as follows:
> > > +The foo_reclaim() function might appear as follows::
> > >
> > >       void foo_reclaim(struct rcu_head *rp)
> > >       {
> > > @@ -552,7 +561,7 @@ o Use call_rcu() -after- removing a data element
> > from an
> > >
> > >  If the callback for call_rcu() is not doing anything more than calling
> > >  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> > > -to avoid having to write your own callback:
> > > +to avoid having to write your own callback::
> > >
> > >       kfree_rcu(old_fp, rcu);
> > >
> > > @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> > governing the use of RCU.
> > >
> > >
> > >  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> > > +------------------------------------------------
> > >
> > >  One of the nice things about RCU is that it has extremely simple "toy"
> > >  implementations that are a good first step towards understanding the
> > > @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> > deadlock.
> > >  However, it is probably the easiest implementation to relate to, so is
> > >  a good starting point.
> > >
> > > -It is extremely simple:
> > > +It is extremely simple::
> > >
> > >       static DEFINE_RWLOCK(rcu_gp_mutex);
> > >
> > > @@ -614,7 +624,7 @@ It is extremely simple:
> > >
> > >  [You can ignore rcu_assign_pointer() and rcu_dereference() without
> > missing
> > >  much.  But here are simplified versions anyway.  And whatever you do,
> > > -don't forget about them when submitting patches making use of RCU!]
> > > +don't forget about them when submitting patches making use of RCU!]::
> > >
> > >       #define rcu_assign_pointer(p, v) \
> > >       ({ \
> > > @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation
> > that is based on
> > >  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
> > >  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
> > >  are the same as those shown in the preceding section, so they are
> > omitted.
> > > +::
> > >
> > >       void rcu_read_lock(void) { }
> > >
> > > @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an
> > RCU read-side
> > >
> > >
> > >  6.  ANALOGY WITH READER-WRITER LOCKING
> > > +--------------------------------------
> > >
> > >  Although RCU can be used in many different ways, a very common use of
> > >  RCU is analogous to reader-writer locking.  The following unified
> > >  diff shows how closely related RCU and reader-writer locking can be.
> > > +::
> > >
> > >       @@ -5,5 +5,5 @@ struct el {
> > >               int data;
> > > @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> > locking can be.
> > >               return 0;
> > >        }
> > >
> > > -Or, for those who prefer a side-by-side listing:
> > > +Or, for those who prefer a side-by-side listing::
> > >
> > >   1 struct el {                          1 struct el {
> > >   2   struct list_head list;             2   struct list_head list;
> > > @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
> > >   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
> > >   9 struct el head;                      9 struct el head;
> > >
> > > - 1 int search(long key, int *result)    1 int search(long key, int
> > *result)
> > > - 2 {                                    2 {
> > > - 3   struct list_head *lp;              3   struct list_head *lp;
> > > - 4   struct el *p;                      4   struct el *p;
> > > - 5                                      5
> > > - 6   read_lock(&listmutex);             6   rcu_read_lock();
> > > - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> > head, lp) {
> > > - 8     if (p->key == key) {             8     if (p->key == key) {
> > > - 9       *result = p->data;             9       *result = p->data;
> > > -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > > -11       return 1;                     11       return 1;
> > > -12     }                               12     }
> > > -13   }                                 13   }
> > > -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > > -15   return 0;                         15   return 0;
> > > -16 }                                   16 }
> > > -
> > > - 1 int delete(long key)                 1 int delete(long key)
> > > - 2 {                                    2 {
> > > - 3   struct el *p;                      3   struct el *p;
> > > - 4                                      4
> > > - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > > - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> > head, lp) {
> > > - 7     if (p->key == key) {             7     if (p->key == key) {
> > > - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > > - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> > > -                                       10       synchronize_rcu();
> > > -10       kfree(p);                     11       kfree(p);
> > > -11       return 1;                     12       return 1;
> > > -12     }                               13     }
> > > -13   }                                 14   }
> > > -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > > -15   return 0;                         16   return 0;
> > > -16 }                                   17 }
> > > +::
> > > +
> > > +  1 int search(long key, int *result)    1 int search(long key, int
> > *result)
> > > +  2 {                                    2 {
> > > +  3   struct list_head *lp;              3   struct list_head *lp;
> > > +  4   struct el *p;                      4   struct el *p;
> > > +  5                                      5
> > > +  6   read_lock(&listmutex);             6   rcu_read_lock();
> > > +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> > head, lp) {
> > > +  8     if (p->key == key) {             8     if (p->key == key) {
> > > +  9       *result = p->data;             9       *result = p->data;
> > > + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > > + 11       return 1;                     11       return 1;
> > > + 12     }                               12     }
> > > + 13   }                                 13   }
> > > + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > > + 15   return 0;                         15   return 0;
> > > + 16 }                                   16 }
> > > +
> > > +::
> > > +
> > > +  1 int delete(long key)                 1 int delete(long key)
> > > +  2 {                                    2 {
> > > +  3   struct el *p;                      3   struct el *p;
> > > +  4                                      4
> > > +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > > +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> > head, lp) {
> > > +  7     if (p->key == key) {             7     if (p->key == key) {
> > > +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > > +  9       write_unlock(&listmutex);      9
> >  spin_unlock(&listmutex);
> > > +                                        10       synchronize_rcu();
> > > + 10       kfree(p);                     11       kfree(p);
> > > + 11       return 1;                     12       return 1;
> > > + 12     }                               13     }
> > > + 13   }                                 14   }
> > > + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > > + 15   return 0;                         16   return 0;
> > > + 16 }                                   17 }
> > >
> > >  Either way, the differences are quite small.  Read-side locking moves
> > >  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> > > @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
> > >
> > >
> > >  7.  FULL LIST OF RCU APIs
> > > +-------------------------
> > >
> > >  The RCU APIs are documented in docbook-format header comments in the
> > >  Linux-kernel source code, but it helps to have a full list of the
> > >  APIs, since there does not appear to be a way to categorize them
> > >  in docbook.  Here is the list, by category.
> > >
> > > -RCU list traversal:
> > > +RCU list traversal::
> > >
> > >       list_entry_rcu
> > >       list_first_entry_rcu
> > > @@ -854,7 +872,7 @@ RCU list traversal:
> > >       hlist_bl_first_rcu
> > >       hlist_bl_for_each_entry_rcu
> > >
> > > -RCU pointer/list update:
> > > +RCU pointer/list udate::
> > >
> > >       rcu_assign_pointer
> > >       list_add_rcu
> > > @@ -876,7 +894,9 @@ RCU pointer/list update:
> > >       hlist_bl_del_rcu
> > >       hlist_bl_set_first_rcu
> > >
> > > -RCU: Critical sections       Grace period            Barrier
> > > +RCU::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock           synchronize_net         rcu_barrier
> > >       rcu_read_unlock         synchronize_rcu
> > > @@ -885,7 +905,9 @@ RCU:      Critical sections       Grace period
> >       Barrier
> > >       rcu_dereference_check   kfree_rcu
> > >       rcu_dereference_protected
> > >
> > > -bh:  Critical sections       Grace period            Barrier
> > > +bh::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock_bh        call_rcu                rcu_barrier
> > >       rcu_read_unlock_bh      synchronize_rcu
> > > @@ -896,7 +918,9 @@ bh:       Critical sections       Grace period
> >       Barrier
> > >       rcu_dereference_bh_protected
> > >       rcu_read_lock_bh_held
> > >
> > > -sched:       Critical sections       Grace period            Barrier
> > > +sched::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock_sched     call_rcu                rcu_barrier
> > >       rcu_read_unlock_sched   synchronize_rcu
> > > @@ -910,7 +934,9 @@ sched:    Critical sections       Grace period
> >       Barrier
> > >       rcu_read_lock_sched_held
> > >
> > >
> > > -SRCU:        Critical sections       Grace period            Barrier
> > > +SRCU::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       srcu_read_lock          call_srcu               srcu_barrier
> > >       srcu_read_unlock        synchronize_srcu
> > > @@ -918,13 +944,14 @@ SRCU:   Critical sections       Grace period
> >       Barrier
> > >       srcu_dereference_check
> > >       srcu_read_lock_held
> > >
> > > -SRCU:        Initialization/cleanup
> > > +SRCU: Initialization/cleanup::
> > > +
> > >       DEFINE_SRCU
> > >       DEFINE_STATIC_SRCU
> > >       init_srcu_struct
> > >       cleanup_srcu_struct
> > >
> > > -All:  lockdep-checked RCU-protected pointer access
> > > +All: lockdep-checked RCU-protected pointer access::
> > >
> > >       rcu_access_pointer
> > >       rcu_dereference_raw
> > > @@ -976,6 +1003,7 @@ the right tool for your job.
> > >
> > >
> > >  8.  ANSWERS TO QUICK QUIZZES
> > > +----------------------------
> > >
> > >  Quick Quiz #1:       Why is this argument naive?  How could a deadlock
> > >               occur when using this algorithm in a real-world Linux
> > > --
> > > 2.20.1
> > >
> >

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
@ 2019-11-01  7:53       ` paulmck
  2019-11-01  7:53       ` Paul E. McKenney
  1 sibling, 0 replies; 23+ messages in thread
From: paulmck @ 2019-11-01  7:53 UTC (permalink / raw)


On Fri, Nov 01, 2019 at 09:03:57AM +0530, Madhuparna Bhowmik wrote:
> On Fri, 1 Nov, 2019, 4:24 AM Paul E. McKenney, <paulmck at kernel.org> wrote:
> 
> > On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> > > Sync the format with current state of kernel documentation.
> > > This change base on rcu-dev branch
> > > what changed:
> > > - Format bullet lists
> > > - Add literal blocks
> > >
> > > Signed-off-by: Phong Tran <tranmanphong at gmail.com>
> >
> > Queued and pushed with updated subject line and commit log, thank you!
> >
> > Could you and Madhuparna please review and test each other's
> > .rst-conversion patches?
> >
> 
> Sure, I will do it.

Thank you, Madhuparna!

							Thanx, Paul

> Regards
> Madhuparna
> 
> 
> >                                                         Thanx, Paul
> >
> > > ---
> > >  Documentation/RCU/index.rst                   |   1 +
> > >  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
> > >  2 files changed, 90 insertions(+), 61 deletions(-)
> > >  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> > >
> > > diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> > > index 627128c230dc..b9b11481c727 100644
> > > --- a/Documentation/RCU/index.rst
> > > +++ b/Documentation/RCU/index.rst
> > > @@ -8,6 +8,7 @@ RCU concepts
> > >     :maxdepth: 3
> > >
> > >     arrayRCU
> > > +   whatisRCU
> > >     rcu
> > >     listRCU
> > >     NMI-RCU
> > > diff --git a/Documentation/RCU/whatisRCU.txt
> > b/Documentation/RCU/whatisRCU.rst
> > > similarity index 91%
> > > rename from Documentation/RCU/whatisRCU.txt
> > > rename to Documentation/RCU/whatisRCU.rst
> > > index 58ba05c4d97f..70d0e4c21917 100644
> > > --- a/Documentation/RCU/whatisRCU.txt
> > > +++ b/Documentation/RCU/whatisRCU.rst
> > > @@ -1,15 +1,18 @@
> > > +.. _rcu_doc:
> > > +
> > >  What is RCU?  --  "Read, Copy, Update"
> > > +======================================
> > >
> > >  Please note that the "What is RCU?" LWN series is an excellent place
> > >  to start learning about RCU:
> > >
> > > -1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > > -2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > > -3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > > -4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > > -     2010 Big API Table           http://lwn.net/Articles/419086/
> > > -5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > > -     2014 Big API Table           http://lwn.net/Articles/609973/
> > > +| 1. What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > > +| 2. What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > > +| 3. RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > > +| 4. The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > > +|    2010 Big API Table           http://lwn.net/Articles/419086/
> > > +| 5. The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > > +|    2014 Big API Table           http://lwn.net/Articles/609973/
> > >
> > >
> > >  What is RCU?
> > > @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
> > >
> > >
> > >  1.  RCU OVERVIEW
> > > +----------------
> > >
> > >  The basic idea behind RCU is to split updates into "removal" and
> > >  "reclamation" phases.  The removal phase removes references to data
> > items
> > > @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
> > >
> > >
> > >  2.  WHAT IS RCU'S CORE API?
> > > +---------------------------
> > >
> > >  The core RCU API is quite small:
> > >
> > > @@ -166,7 +171,7 @@ synchronize_rcu()
> > >       read-side critical sections on all CPUs have completed.
> > >       Note that synchronize_rcu() will -not- necessarily wait for
> > >       any subsequent RCU read-side critical sections to complete.
> > > -     For example, consider the following sequence of events:
> > > +     For example, consider the following sequence of events::
> > >
> > >                CPU 0                  CPU 1                 CPU 2
> > >            ----------------- ------------------------- ---------------
> > > @@ -248,13 +253,13 @@ rcu_dereference()
> > >
> > >       Common coding practice uses rcu_dereference() to copy an
> > >       RCU-protected pointer to a local variable, then dereferences
> > > -     this local variable, for example as follows:
> > > +     this local variable, for example as follows::
> > >
> > >               p = rcu_dereference(head.next);
> > >               return p->data;
> > >
> > >       However, in this case, one could just as easily combine these
> > > -     into one statement:
> > > +     into one statement::
> > >
> > >               return rcu_dereference(head.next)->data;
> > >
> > > @@ -267,7 +272,7 @@ rcu_dereference()
> > >
> > >       Note that the value returned by rcu_dereference() is valid
> > >       only within the enclosing RCU read-side critical section [1].
> > > -     For example, the following is -not- legal:
> > > +     For example, the following is -not- legal::
> > >
> > >               rcu_read_lock();
> > >               p = rcu_dereference(head.next);
> > > @@ -315,6 +320,7 @@ rcu_dereference()
> > >
> > >  The following diagram shows how each API communicates among the
> > >  reader, updater, and reclaimer.
> > > +::
> > >
> > >
> > >           rcu_assign_pointer()
> > > @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
> > >
> > >
> > >  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> > > +-----------------------------------------------
> > >
> > >  This section shows a simple use of the core RCU API to protect a
> > >  global pointer to a dynamically allocated structure.  More-typical
> > >  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> > > +::
> > >
> > >       struct foo {
> > >               int a;
> > > @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
> > >
> > >
> > >  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> > > +--------------------------------------------
> > >
> > >  In the example above, foo_update_a() blocks until a grace period
> > elapses.
> > >  This is quite simple, but in some cases one cannot afford to wait so
> > >  long -- there might be other high-priority work to be done.
> > >
> > >  In such cases, one uses call_rcu() rather than synchronize_rcu().
> > > -The call_rcu() API is as follows:
> > > +The call_rcu() API is as follows::
> > >
> > >       void call_rcu(struct rcu_head * head,
> > >                     void (*func)(struct rcu_head *head));
> > > @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
> > >  This function invokes func(head) after a grace period has elapsed.
> > >  This invocation might happen from either softirq or process context,
> > >  so the function is not permitted to block.  The foo struct needs to
> > > -have an rcu_head structure added, perhaps as follows:
> > > +have an rcu_head structure added, perhaps as follows::
> > >
> > >       struct foo {
> > >               int a;
> > > @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
> > >               struct rcu_head rcu;
> > >       };
> > >
> > > -The foo_update_a() function might then be written as follows:
> > > +The foo_update_a() function might then be written as follows::
> > >
> > >       /*
> > >        * Create a new struct foo that is the same as the one currently
> > > @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> > follows:
> > >               call_rcu(&old_fp->rcu, foo_reclaim);
> > >       }
> > >
> > > -The foo_reclaim() function might appear as follows:
> > > +The foo_reclaim() function might appear as follows::
> > >
> > >       void foo_reclaim(struct rcu_head *rp)
> > >       {
> > > @@ -552,7 +561,7 @@ o Use call_rcu() -after- removing a data element
> > from an
> > >
> > >  If the callback for call_rcu() is not doing anything more than calling
> > >  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> > > -to avoid having to write your own callback:
> > > +to avoid having to write your own callback::
> > >
> > >       kfree_rcu(old_fp, rcu);
> > >
> > > @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> > governing the use of RCU.
> > >
> > >
> > >  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> > > +------------------------------------------------
> > >
> > >  One of the nice things about RCU is that it has extremely simple "toy"
> > >  implementations that are a good first step towards understanding the
> > > @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> > deadlock.
> > >  However, it is probably the easiest implementation to relate to, so is
> > >  a good starting point.
> > >
> > > -It is extremely simple:
> > > +It is extremely simple::
> > >
> > >       static DEFINE_RWLOCK(rcu_gp_mutex);
> > >
> > > @@ -614,7 +624,7 @@ It is extremely simple:
> > >
> > >  [You can ignore rcu_assign_pointer() and rcu_dereference() without
> > missing
> > >  much.  But here are simplified versions anyway.  And whatever you do,
> > > -don't forget about them when submitting patches making use of RCU!]
> > > +don't forget about them when submitting patches making use of RCU!]::
> > >
> > >       #define rcu_assign_pointer(p, v) \
> > >       ({ \
> > > @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation
> > that is based on
> > >  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
> > >  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
> > >  are the same as those shown in the preceding section, so they are
> > omitted.
> > > +::
> > >
> > >       void rcu_read_lock(void) { }
> > >
> > > @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an
> > RCU read-side
> > >
> > >
> > >  6.  ANALOGY WITH READER-WRITER LOCKING
> > > +--------------------------------------
> > >
> > >  Although RCU can be used in many different ways, a very common use of
> > >  RCU is analogous to reader-writer locking.  The following unified
> > >  diff shows how closely related RCU and reader-writer locking can be.
> > > +::
> > >
> > >       @@ -5,5 +5,5 @@ struct el {
> > >               int data;
> > > @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> > locking can be.
> > >               return 0;
> > >        }
> > >
> > > -Or, for those who prefer a side-by-side listing:
> > > +Or, for those who prefer a side-by-side listing::
> > >
> > >   1 struct el {                          1 struct el {
> > >   2   struct list_head list;             2   struct list_head list;
> > > @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
> > >   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
> > >   9 struct el head;                      9 struct el head;
> > >
> > > - 1 int search(long key, int *result)    1 int search(long key, int
> > *result)
> > > - 2 {                                    2 {
> > > - 3   struct list_head *lp;              3   struct list_head *lp;
> > > - 4   struct el *p;                      4   struct el *p;
> > > - 5                                      5
> > > - 6   read_lock(&listmutex);             6   rcu_read_lock();
> > > - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> > head, lp) {
> > > - 8     if (p->key == key) {             8     if (p->key == key) {
> > > - 9       *result = p->data;             9       *result = p->data;
> > > -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > > -11       return 1;                     11       return 1;
> > > -12     }                               12     }
> > > -13   }                                 13   }
> > > -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > > -15   return 0;                         15   return 0;
> > > -16 }                                   16 }
> > > -
> > > - 1 int delete(long key)                 1 int delete(long key)
> > > - 2 {                                    2 {
> > > - 3   struct el *p;                      3   struct el *p;
> > > - 4                                      4
> > > - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > > - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> > head, lp) {
> > > - 7     if (p->key == key) {             7     if (p->key == key) {
> > > - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > > - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> > > -                                       10       synchronize_rcu();
> > > -10       kfree(p);                     11       kfree(p);
> > > -11       return 1;                     12       return 1;
> > > -12     }                               13     }
> > > -13   }                                 14   }
> > > -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > > -15   return 0;                         16   return 0;
> > > -16 }                                   17 }
> > > +::
> > > +
> > > +  1 int search(long key, int *result)    1 int search(long key, int
> > *result)
> > > +  2 {                                    2 {
> > > +  3   struct list_head *lp;              3   struct list_head *lp;
> > > +  4   struct el *p;                      4   struct el *p;
> > > +  5                                      5
> > > +  6   read_lock(&listmutex);             6   rcu_read_lock();
> > > +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> > head, lp) {
> > > +  8     if (p->key == key) {             8     if (p->key == key) {
> > > +  9       *result = p->data;             9       *result = p->data;
> > > + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > > + 11       return 1;                     11       return 1;
> > > + 12     }                               12     }
> > > + 13   }                                 13   }
> > > + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > > + 15   return 0;                         15   return 0;
> > > + 16 }                                   16 }
> > > +
> > > +::
> > > +
> > > +  1 int delete(long key)                 1 int delete(long key)
> > > +  2 {                                    2 {
> > > +  3   struct el *p;                      3   struct el *p;
> > > +  4                                      4
> > > +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > > +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> > head, lp) {
> > > +  7     if (p->key == key) {             7     if (p->key == key) {
> > > +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > > +  9       write_unlock(&listmutex);      9
> >  spin_unlock(&listmutex);
> > > +                                        10       synchronize_rcu();
> > > + 10       kfree(p);                     11       kfree(p);
> > > + 11       return 1;                     12       return 1;
> > > + 12     }                               13     }
> > > + 13   }                                 14   }
> > > + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > > + 15   return 0;                         16   return 0;
> > > + 16 }                                   17 }
> > >
> > >  Either way, the differences are quite small.  Read-side locking moves
> > >  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> > > @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
> > >
> > >
> > >  7.  FULL LIST OF RCU APIs
> > > +-------------------------
> > >
> > >  The RCU APIs are documented in docbook-format header comments in the
> > >  Linux-kernel source code, but it helps to have a full list of the
> > >  APIs, since there does not appear to be a way to categorize them
> > >  in docbook.  Here is the list, by category.
> > >
> > > -RCU list traversal:
> > > +RCU list traversal::
> > >
> > >       list_entry_rcu
> > >       list_first_entry_rcu
> > > @@ -854,7 +872,7 @@ RCU list traversal:
> > >       hlist_bl_first_rcu
> > >       hlist_bl_for_each_entry_rcu
> > >
> > > -RCU pointer/list update:
> > > +RCU pointer/list udate::
> > >
> > >       rcu_assign_pointer
> > >       list_add_rcu
> > > @@ -876,7 +894,9 @@ RCU pointer/list update:
> > >       hlist_bl_del_rcu
> > >       hlist_bl_set_first_rcu
> > >
> > > -RCU: Critical sections       Grace period            Barrier
> > > +RCU::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock           synchronize_net         rcu_barrier
> > >       rcu_read_unlock         synchronize_rcu
> > > @@ -885,7 +905,9 @@ RCU:      Critical sections       Grace period
> >       Barrier
> > >       rcu_dereference_check   kfree_rcu
> > >       rcu_dereference_protected
> > >
> > > -bh:  Critical sections       Grace period            Barrier
> > > +bh::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock_bh        call_rcu                rcu_barrier
> > >       rcu_read_unlock_bh      synchronize_rcu
> > > @@ -896,7 +918,9 @@ bh:       Critical sections       Grace period
> >       Barrier
> > >       rcu_dereference_bh_protected
> > >       rcu_read_lock_bh_held
> > >
> > > -sched:       Critical sections       Grace period            Barrier
> > > +sched::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock_sched     call_rcu                rcu_barrier
> > >       rcu_read_unlock_sched   synchronize_rcu
> > > @@ -910,7 +934,9 @@ sched:    Critical sections       Grace period
> >       Barrier
> > >       rcu_read_lock_sched_held
> > >
> > >
> > > -SRCU:        Critical sections       Grace period            Barrier
> > > +SRCU::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       srcu_read_lock          call_srcu               srcu_barrier
> > >       srcu_read_unlock        synchronize_srcu
> > > @@ -918,13 +944,14 @@ SRCU:   Critical sections       Grace period
> >       Barrier
> > >       srcu_dereference_check
> > >       srcu_read_lock_held
> > >
> > > -SRCU:        Initialization/cleanup
> > > +SRCU: Initialization/cleanup::
> > > +
> > >       DEFINE_SRCU
> > >       DEFINE_STATIC_SRCU
> > >       init_srcu_struct
> > >       cleanup_srcu_struct
> > >
> > > -All:  lockdep-checked RCU-protected pointer access
> > > +All: lockdep-checked RCU-protected pointer access::
> > >
> > >       rcu_access_pointer
> > >       rcu_dereference_raw
> > > @@ -976,6 +1003,7 @@ the right tool for your job.
> > >
> > >
> > >  8.  ANSWERS TO QUICK QUIZZES
> > > +----------------------------
> > >
> > >  Quick Quiz #1:       Why is this argument naive?  How could a deadlock
> > >               occur when using this algorithm in a real-world Linux
> > > --
> > > 2.20.1
> > >
> >

^ permalink raw reply	[flat|nested] 23+ messages in thread

* Re: [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
  2019-11-01  7:53       ` paulmck
@ 2019-11-01  7:53       ` Paul E. McKenney
  1 sibling, 0 replies; 23+ messages in thread
From: Paul E. McKenney @ 2019-11-01  7:53 UTC (permalink / raw)
  To: Madhuparna Bhowmik
  Cc: corbet, linux-doc, jiangshanlai, josh, rostedt, linux-kernel,
	rcu, mathieu.desnoyers, joel, linux-kernel-mentees

On Fri, Nov 01, 2019 at 09:03:57AM +0530, Madhuparna Bhowmik wrote:
> On Fri, 1 Nov, 2019, 4:24 AM Paul E. McKenney, <paulmck@kernel.org> wrote:
> 
> > On Thu, Oct 31, 2019 at 06:31:28AM +0700, Phong Tran wrote:
> > > Sync the format with current state of kernel documentation.
> > > This change base on rcu-dev branch
> > > what changed:
> > > - Format bullet lists
> > > - Add literal blocks
> > >
> > > Signed-off-by: Phong Tran <tranmanphong@gmail.com>
> >
> > Queued and pushed with updated subject line and commit log, thank you!
> >
> > Could you and Madhuparna please review and test each other's
> > .rst-conversion patches?
> >
> 
> Sure, I will do it.

Thank you, Madhuparna!

							Thanx, Paul

> Regards
> Madhuparna
> 
> 
> >                                                         Thanx, Paul
> >
> > > ---
> > >  Documentation/RCU/index.rst                   |   1 +
> > >  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
> > >  2 files changed, 90 insertions(+), 61 deletions(-)
> > >  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
> > >
> > > diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> > > index 627128c230dc..b9b11481c727 100644
> > > --- a/Documentation/RCU/index.rst
> > > +++ b/Documentation/RCU/index.rst
> > > @@ -8,6 +8,7 @@ RCU concepts
> > >     :maxdepth: 3
> > >
> > >     arrayRCU
> > > +   whatisRCU
> > >     rcu
> > >     listRCU
> > >     NMI-RCU
> > > diff --git a/Documentation/RCU/whatisRCU.txt
> > b/Documentation/RCU/whatisRCU.rst
> > > similarity index 91%
> > > rename from Documentation/RCU/whatisRCU.txt
> > > rename to Documentation/RCU/whatisRCU.rst
> > > index 58ba05c4d97f..70d0e4c21917 100644
> > > --- a/Documentation/RCU/whatisRCU.txt
> > > +++ b/Documentation/RCU/whatisRCU.rst
> > > @@ -1,15 +1,18 @@
> > > +.. _rcu_doc:
> > > +
> > >  What is RCU?  --  "Read, Copy, Update"
> > > +======================================
> > >
> > >  Please note that the "What is RCU?" LWN series is an excellent place
> > >  to start learning about RCU:
> > >
> > > -1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > > -2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > > -3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > > -4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > > -     2010 Big API Table           http://lwn.net/Articles/419086/
> > > -5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > > -     2014 Big API Table           http://lwn.net/Articles/609973/
> > > +| 1. What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> > > +| 2. What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> > > +| 3. RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> > > +| 4. The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> > > +|    2010 Big API Table           http://lwn.net/Articles/419086/
> > > +| 5. The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> > > +|    2014 Big API Table           http://lwn.net/Articles/609973/
> > >
> > >
> > >  What is RCU?
> > > @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
> > >
> > >
> > >  1.  RCU OVERVIEW
> > > +----------------
> > >
> > >  The basic idea behind RCU is to split updates into "removal" and
> > >  "reclamation" phases.  The removal phase removes references to data
> > items
> > > @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
> > >
> > >
> > >  2.  WHAT IS RCU'S CORE API?
> > > +---------------------------
> > >
> > >  The core RCU API is quite small:
> > >
> > > @@ -166,7 +171,7 @@ synchronize_rcu()
> > >       read-side critical sections on all CPUs have completed.
> > >       Note that synchronize_rcu() will -not- necessarily wait for
> > >       any subsequent RCU read-side critical sections to complete.
> > > -     For example, consider the following sequence of events:
> > > +     For example, consider the following sequence of events::
> > >
> > >                CPU 0                  CPU 1                 CPU 2
> > >            ----------------- ------------------------- ---------------
> > > @@ -248,13 +253,13 @@ rcu_dereference()
> > >
> > >       Common coding practice uses rcu_dereference() to copy an
> > >       RCU-protected pointer to a local variable, then dereferences
> > > -     this local variable, for example as follows:
> > > +     this local variable, for example as follows::
> > >
> > >               p = rcu_dereference(head.next);
> > >               return p->data;
> > >
> > >       However, in this case, one could just as easily combine these
> > > -     into one statement:
> > > +     into one statement::
> > >
> > >               return rcu_dereference(head.next)->data;
> > >
> > > @@ -267,7 +272,7 @@ rcu_dereference()
> > >
> > >       Note that the value returned by rcu_dereference() is valid
> > >       only within the enclosing RCU read-side critical section [1].
> > > -     For example, the following is -not- legal:
> > > +     For example, the following is -not- legal::
> > >
> > >               rcu_read_lock();
> > >               p = rcu_dereference(head.next);
> > > @@ -315,6 +320,7 @@ rcu_dereference()
> > >
> > >  The following diagram shows how each API communicates among the
> > >  reader, updater, and reclaimer.
> > > +::
> > >
> > >
> > >           rcu_assign_pointer()
> > > @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
> > >
> > >
> > >  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> > > +-----------------------------------------------
> > >
> > >  This section shows a simple use of the core RCU API to protect a
> > >  global pointer to a dynamically allocated structure.  More-typical
> > >  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> > > +::
> > >
> > >       struct foo {
> > >               int a;
> > > @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
> > >
> > >
> > >  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> > > +--------------------------------------------
> > >
> > >  In the example above, foo_update_a() blocks until a grace period
> > elapses.
> > >  This is quite simple, but in some cases one cannot afford to wait so
> > >  long -- there might be other high-priority work to be done.
> > >
> > >  In such cases, one uses call_rcu() rather than synchronize_rcu().
> > > -The call_rcu() API is as follows:
> > > +The call_rcu() API is as follows::
> > >
> > >       void call_rcu(struct rcu_head * head,
> > >                     void (*func)(struct rcu_head *head));
> > > @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
> > >  This function invokes func(head) after a grace period has elapsed.
> > >  This invocation might happen from either softirq or process context,
> > >  so the function is not permitted to block.  The foo struct needs to
> > > -have an rcu_head structure added, perhaps as follows:
> > > +have an rcu_head structure added, perhaps as follows::
> > >
> > >       struct foo {
> > >               int a;
> > > @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
> > >               struct rcu_head rcu;
> > >       };
> > >
> > > -The foo_update_a() function might then be written as follows:
> > > +The foo_update_a() function might then be written as follows::
> > >
> > >       /*
> > >        * Create a new struct foo that is the same as the one currently
> > > @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> > follows:
> > >               call_rcu(&old_fp->rcu, foo_reclaim);
> > >       }
> > >
> > > -The foo_reclaim() function might appear as follows:
> > > +The foo_reclaim() function might appear as follows::
> > >
> > >       void foo_reclaim(struct rcu_head *rp)
> > >       {
> > > @@ -552,7 +561,7 @@ o Use call_rcu() -after- removing a data element
> > from an
> > >
> > >  If the callback for call_rcu() is not doing anything more than calling
> > >  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> > > -to avoid having to write your own callback:
> > > +to avoid having to write your own callback::
> > >
> > >       kfree_rcu(old_fp, rcu);
> > >
> > > @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> > governing the use of RCU.
> > >
> > >
> > >  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> > > +------------------------------------------------
> > >
> > >  One of the nice things about RCU is that it has extremely simple "toy"
> > >  implementations that are a good first step towards understanding the
> > > @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> > deadlock.
> > >  However, it is probably the easiest implementation to relate to, so is
> > >  a good starting point.
> > >
> > > -It is extremely simple:
> > > +It is extremely simple::
> > >
> > >       static DEFINE_RWLOCK(rcu_gp_mutex);
> > >
> > > @@ -614,7 +624,7 @@ It is extremely simple:
> > >
> > >  [You can ignore rcu_assign_pointer() and rcu_dereference() without
> > missing
> > >  much.  But here are simplified versions anyway.  And whatever you do,
> > > -don't forget about them when submitting patches making use of RCU!]
> > > +don't forget about them when submitting patches making use of RCU!]::
> > >
> > >       #define rcu_assign_pointer(p, v) \
> > >       ({ \
> > > @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation
> > that is based on
> > >  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
> > >  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
> > >  are the same as those shown in the preceding section, so they are
> > omitted.
> > > +::
> > >
> > >       void rcu_read_lock(void) { }
> > >
> > > @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an
> > RCU read-side
> > >
> > >
> > >  6.  ANALOGY WITH READER-WRITER LOCKING
> > > +--------------------------------------
> > >
> > >  Although RCU can be used in many different ways, a very common use of
> > >  RCU is analogous to reader-writer locking.  The following unified
> > >  diff shows how closely related RCU and reader-writer locking can be.
> > > +::
> > >
> > >       @@ -5,5 +5,5 @@ struct el {
> > >               int data;
> > > @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> > locking can be.
> > >               return 0;
> > >        }
> > >
> > > -Or, for those who prefer a side-by-side listing:
> > > +Or, for those who prefer a side-by-side listing::
> > >
> > >   1 struct el {                          1 struct el {
> > >   2   struct list_head list;             2   struct list_head list;
> > > @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
> > >   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
> > >   9 struct el head;                      9 struct el head;
> > >
> > > - 1 int search(long key, int *result)    1 int search(long key, int
> > *result)
> > > - 2 {                                    2 {
> > > - 3   struct list_head *lp;              3   struct list_head *lp;
> > > - 4   struct el *p;                      4   struct el *p;
> > > - 5                                      5
> > > - 6   read_lock(&listmutex);             6   rcu_read_lock();
> > > - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> > head, lp) {
> > > - 8     if (p->key == key) {             8     if (p->key == key) {
> > > - 9       *result = p->data;             9       *result = p->data;
> > > -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > > -11       return 1;                     11       return 1;
> > > -12     }                               12     }
> > > -13   }                                 13   }
> > > -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > > -15   return 0;                         15   return 0;
> > > -16 }                                   16 }
> > > -
> > > - 1 int delete(long key)                 1 int delete(long key)
> > > - 2 {                                    2 {
> > > - 3   struct el *p;                      3   struct el *p;
> > > - 4                                      4
> > > - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > > - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> > head, lp) {
> > > - 7     if (p->key == key) {             7     if (p->key == key) {
> > > - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > > - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> > > -                                       10       synchronize_rcu();
> > > -10       kfree(p);                     11       kfree(p);
> > > -11       return 1;                     12       return 1;
> > > -12     }                               13     }
> > > -13   }                                 14   }
> > > -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > > -15   return 0;                         16   return 0;
> > > -16 }                                   17 }
> > > +::
> > > +
> > > +  1 int search(long key, int *result)    1 int search(long key, int
> > *result)
> > > +  2 {                                    2 {
> > > +  3   struct list_head *lp;              3   struct list_head *lp;
> > > +  4   struct el *p;                      4   struct el *p;
> > > +  5                                      5
> > > +  6   read_lock(&listmutex);             6   rcu_read_lock();
> > > +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> > head, lp) {
> > > +  8     if (p->key == key) {             8     if (p->key == key) {
> > > +  9       *result = p->data;             9       *result = p->data;
> > > + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> > > + 11       return 1;                     11       return 1;
> > > + 12     }                               12     }
> > > + 13   }                                 13   }
> > > + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> > > + 15   return 0;                         15   return 0;
> > > + 16 }                                   16 }
> > > +
> > > +::
> > > +
> > > +  1 int delete(long key)                 1 int delete(long key)
> > > +  2 {                                    2 {
> > > +  3   struct el *p;                      3   struct el *p;
> > > +  4                                      4
> > > +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> > > +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
> > head, lp) {
> > > +  7     if (p->key == key) {             7     if (p->key == key) {
> > > +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> > > +  9       write_unlock(&listmutex);      9
> >  spin_unlock(&listmutex);
> > > +                                        10       synchronize_rcu();
> > > + 10       kfree(p);                     11       kfree(p);
> > > + 11       return 1;                     12       return 1;
> > > + 12     }                               13     }
> > > + 13   }                                 14   }
> > > + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> > > + 15   return 0;                         16   return 0;
> > > + 16 }                                   17 }
> > >
> > >  Either way, the differences are quite small.  Read-side locking moves
> > >  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> > > @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
> > >
> > >
> > >  7.  FULL LIST OF RCU APIs
> > > +-------------------------
> > >
> > >  The RCU APIs are documented in docbook-format header comments in the
> > >  Linux-kernel source code, but it helps to have a full list of the
> > >  APIs, since there does not appear to be a way to categorize them
> > >  in docbook.  Here is the list, by category.
> > >
> > > -RCU list traversal:
> > > +RCU list traversal::
> > >
> > >       list_entry_rcu
> > >       list_first_entry_rcu
> > > @@ -854,7 +872,7 @@ RCU list traversal:
> > >       hlist_bl_first_rcu
> > >       hlist_bl_for_each_entry_rcu
> > >
> > > -RCU pointer/list update:
> > > +RCU pointer/list udate::
> > >
> > >       rcu_assign_pointer
> > >       list_add_rcu
> > > @@ -876,7 +894,9 @@ RCU pointer/list update:
> > >       hlist_bl_del_rcu
> > >       hlist_bl_set_first_rcu
> > >
> > > -RCU: Critical sections       Grace period            Barrier
> > > +RCU::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock           synchronize_net         rcu_barrier
> > >       rcu_read_unlock         synchronize_rcu
> > > @@ -885,7 +905,9 @@ RCU:      Critical sections       Grace period
> >       Barrier
> > >       rcu_dereference_check   kfree_rcu
> > >       rcu_dereference_protected
> > >
> > > -bh:  Critical sections       Grace period            Barrier
> > > +bh::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock_bh        call_rcu                rcu_barrier
> > >       rcu_read_unlock_bh      synchronize_rcu
> > > @@ -896,7 +918,9 @@ bh:       Critical sections       Grace period
> >       Barrier
> > >       rcu_dereference_bh_protected
> > >       rcu_read_lock_bh_held
> > >
> > > -sched:       Critical sections       Grace period            Barrier
> > > +sched::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       rcu_read_lock_sched     call_rcu                rcu_barrier
> > >       rcu_read_unlock_sched   synchronize_rcu
> > > @@ -910,7 +934,9 @@ sched:    Critical sections       Grace period
> >       Barrier
> > >       rcu_read_lock_sched_held
> > >
> > >
> > > -SRCU:        Critical sections       Grace period            Barrier
> > > +SRCU::
> > > +
> > > +     Critical sections       Grace period            Barrier
> > >
> > >       srcu_read_lock          call_srcu               srcu_barrier
> > >       srcu_read_unlock        synchronize_srcu
> > > @@ -918,13 +944,14 @@ SRCU:   Critical sections       Grace period
> >       Barrier
> > >       srcu_dereference_check
> > >       srcu_read_lock_held
> > >
> > > -SRCU:        Initialization/cleanup
> > > +SRCU: Initialization/cleanup::
> > > +
> > >       DEFINE_SRCU
> > >       DEFINE_STATIC_SRCU
> > >       init_srcu_struct
> > >       cleanup_srcu_struct
> > >
> > > -All:  lockdep-checked RCU-protected pointer access
> > > +All: lockdep-checked RCU-protected pointer access::
> > >
> > >       rcu_access_pointer
> > >       rcu_dereference_raw
> > > @@ -976,6 +1003,7 @@ the right tool for your job.
> > >
> > >
> > >  8.  ANSWERS TO QUICK QUIZZES
> > > +----------------------------
> > >
> > >  Quick Quiz #1:       Why is this argument naive?  How could a deadlock
> > >               occur when using this algorithm in a real-world Linux
> > > --
> > > 2.20.1
> > >
> >
_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-10-30 23:31 [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst tranmanphong at gmail.com (Phong Tran)
  2019-10-30 23:31 ` tranmanphong
  2019-10-31 22:54 ` paulmck at kernel.org (Paul E. McKenney)
@ 2019-11-02  8:31 ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  2019-11-02  8:31   ` madhuparnabhowmik04
                     ` (2 more replies)
  2 siblings, 3 replies; 23+ messages in thread
From: madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik) @ 2019-11-02  8:31 UTC (permalink / raw)


I reviewed this patch, and I have the following suggestions:

On Thu, Oct 31, 2019 at 5:04 AM Phong Tran <tranmanphong at gmail.com> wrote:

> Sync the format with current state of kernel documentation.
> This change base on rcu-dev branch
> what changed:
> - Format bullet lists
> - Add literal blocks
>
> Signed-off-by: Phong Tran <tranmanphong at gmail.com>
> ---
>  Documentation/RCU/index.rst                   |   1 +
>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>  2 files changed, 90 insertions(+), 61 deletions(-)
>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
>
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index 627128c230dc..b9b11481c727 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 3
>
>     arrayRCU
> +   whatisRCU
>     rcu
>     listRCU
>     NMI-RCU
> diff --git a/Documentation/RCU/whatisRCU.txt
> b/Documentation/RCU/whatisRCU.rst
> similarity index 91%
> rename from Documentation/RCU/whatisRCU.txt
> rename to Documentation/RCU/whatisRCU.rst
> index 58ba05c4d97f..70d0e4c21917 100644
> --- a/Documentation/RCU/whatisRCU.txt
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -1,15 +1,18 @@
> +.. _rcu_doc:
> +
>  What is RCU?  --  "Read, Copy, Update"
> +======================================
>
>  Please note that the "What is RCU?" LWN series is an excellent place
>  to start learning about RCU:
>
> -1.     What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> -2.     What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> -3.     RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> -4.     The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> -       2010 Big API Table           http://lwn.net/Articles/419086/
> -5.     The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> -       2014 Big API Table           http://lwn.net/Articles/609973/
> +| 1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> +| 2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> +| 3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> +| 4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> +|      2010 Big API Table           http://lwn.net/Articles/419086/
> +| 5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> +|      2014 Big API Table           http://lwn.net/Articles/609973/
>
>
Adding an external link here would be better.
like this :  `text <link URL>`_

 What is RCU?
> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>
>
>
There is a list of topics that are covered in this documentation.
Like this:

1. RCU OVERVIEW
2. WHAT IS RCU?S CORE API?
3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
...

 since this document is quite big adding cross-references to the above
would be helpful.


>  1.  RCU OVERVIEW
> +----------------
>
>  The basic idea behind RCU is to split updates into "removal" and
>  "reclamation" phases.  The removal phase removes references to data items
> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>
>
>  2.  WHAT IS RCU'S CORE API?
> +---------------------------
>
>  The core RCU API is quite small:
>
> @@ -166,7 +171,7 @@ synchronize_rcu()
>         read-side critical sections on all CPUs have completed.
>         Note that synchronize_rcu() will -not- necessarily wait for
>         any subsequent RCU read-side critical sections to complete.
> -       For example, consider the following sequence of events:
> +       For example, consider the following sequence of events::
>
>                  CPU 0                  CPU 1                 CPU 2
>              ----------------- ------------------------- ---------------
> @@ -248,13 +253,13 @@ rcu_dereference()
>
>         Common coding practice uses rcu_dereference() to copy an
>         RCU-protected pointer to a local variable, then dereferences
> -       this local variable, for example as follows:
> +       this local variable, for example as follows::
>
>                 p = rcu_dereference(head.next);
>                 return p->data;
>
>         However, in this case, one could just as easily combine these
> -       into one statement:
> +       into one statement::
>
>                 return rcu_dereference(head.next)->data;
>
> @@ -267,7 +272,7 @@ rcu_dereference()
>
>         Note that the value returned by rcu_dereference() is valid
>         only within the enclosing RCU read-side critical section [1].
> -       For example, the following is -not- legal:
> +       For example, the following is -not- legal::
>
>                 rcu_read_lock();
>                 p = rcu_dereference(head.next);
> @@ -315,6 +320,7 @@ rcu_dereference()
>
>  The following diagram shows how each API communicates among the
>  reader, updater, and reclaimer.
> +::
>
>
>             rcu_assign_pointer()
> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>
>
>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> +-----------------------------------------------
>
>  This section shows a simple use of the core RCU API to protect a
>  global pointer to a dynamically allocated structure.  More-typical
>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> +::
>
>         struct foo {
>                 int a;
> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>
>
>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> +--------------------------------------------
>
>  In the example above, foo_update_a() blocks until a grace period elapses.
>  This is quite simple, but in some cases one cannot afford to wait so
>  long -- there might be other high-priority work to be done.
>
>  In such cases, one uses call_rcu() rather than synchronize_rcu().
> -The call_rcu() API is as follows:
> +The call_rcu() API is as follows::
>
>         void call_rcu(struct rcu_head * head,
>                       void (*func)(struct rcu_head *head));
> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>  This function invokes func(head) after a grace period has elapsed.
>  This invocation might happen from either softirq or process context,
>  so the function is not permitted to block.  The foo struct needs to
> -have an rcu_head structure added, perhaps as follows:
> +have an rcu_head structure added, perhaps as follows::
>
>         struct foo {
>                 int a;
> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>                 struct rcu_head rcu;
>         };
>
> -The foo_update_a() function might then be written as follows:
> +The foo_update_a() function might then be written as follows::
>
>         /*
>          * Create a new struct foo that is the same as the one currently
> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> follows:
>                 call_rcu(&old_fp->rcu, foo_reclaim);
>         }
>
> -The foo_reclaim() function might appear as follows:
> +The foo_reclaim() function might appear as follows::
>
>         void foo_reclaim(struct rcu_head *rp)
>         {
> @@ -552,7 +561,7 @@ o   Use call_rcu() -after- removing a data element
> from an
>
>  If the callback for call_rcu() is not doing anything more than calling
>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> -to avoid having to write your own callback:
> +to avoid having to write your own callback::
>
>         kfree_rcu(old_fp, rcu);
>
> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> governing the use of RCU.
>
>
>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> +------------------------------------------------
>
>  One of the nice things about RCU is that it has extremely simple "toy"
>  implementations that are a good first step towards understanding the
> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> deadlock.
>  However, it is probably the easiest implementation to relate to, so is
>  a good starting point.
>
> -It is extremely simple:
> +It is extremely simple::
>
>         static DEFINE_RWLOCK(rcu_gp_mutex);
>
> @@ -614,7 +624,7 @@ It is extremely simple:
>
>  [You can ignore rcu_assign_pointer() and rcu_dereference() without missing
>  much.  But here are simplified versions anyway.  And whatever you do,
> -don't forget about them when submitting patches making use of RCU!]
> +don't forget about them when submitting patches making use of RCU!]::
>
>         #define rcu_assign_pointer(p, v) \
>         ({ \
> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that
> is based on
>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>  are the same as those shown in the preceding section, so they are omitted.
> +::
>
>         void rcu_read_lock(void) { }
>
> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU
> read-side
>
>
>  6.  ANALOGY WITH READER-WRITER LOCKING
> +--------------------------------------
>
>  Although RCU can be used in many different ways, a very common use of
>  RCU is analogous to reader-writer locking.  The following unified
>  diff shows how closely related RCU and reader-writer locking can be.
> +::
>
>         @@ -5,5 +5,5 @@ struct el {
>                 int data;
> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> locking can be.
>                 return 0;
>          }
>
> -Or, for those who prefer a side-by-side listing:
> +Or, for those who prefer a side-by-side listing::
>
>   1 struct el {                          1 struct el {
>   2   struct list_head list;             2   struct list_head list;
> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>   9 struct el head;                      9 struct el head;
>
> - 1 int search(long key, int *result)    1 int search(long key, int
> *result)
> - 2 {                                    2 {
> - 3   struct list_head *lp;              3   struct list_head *lp;
> - 4   struct el *p;                      4   struct el *p;
> - 5                                      5
> - 6   read_lock(&listmutex);             6   rcu_read_lock();
> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> - 8     if (p->key == key) {             8     if (p->key == key) {
> - 9       *result = p->data;             9       *result = p->data;
> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> -11       return 1;                     11       return 1;
> -12     }                               12     }
> -13   }                                 13   }
> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> -15   return 0;                         15   return 0;
> -16 }                                   16 }
> -
> - 1 int delete(long key)                 1 int delete(long key)
> - 2 {                                    2 {
> - 3   struct el *p;                      3   struct el *p;
> - 4                                      4
> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
> lp) {
> - 7     if (p->key == key) {             7     if (p->key == key) {
> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> -                                       10       synchronize_rcu();
> -10       kfree(p);                     11       kfree(p);
> -11       return 1;                     12       return 1;
> -12     }                               13     }
> -13   }                                 14   }
> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> -15   return 0;                         16   return 0;
> -16 }                                   17 }
> +::
> +
> +  1 int search(long key, int *result)    1 int search(long key, int
> *result)
> +  2 {                                    2 {
> +  3   struct list_head *lp;              3   struct list_head *lp;
> +  4   struct el *p;                      4   struct el *p;
> +  5                                      5
> +  6   read_lock(&listmutex);             6   rcu_read_lock();
> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> +  8     if (p->key == key) {             8     if (p->key == key) {
> +  9       *result = p->data;             9       *result = p->data;
> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> + 11       return 1;                     11       return 1;
> + 12     }                               12     }
> + 13   }                                 13   }
> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> + 15   return 0;                         15   return 0;
> + 16 }                                   16 }
> +
> +::
> +
> +  1 int delete(long key)                 1 int delete(long key)
> +  2 {                                    2 {
> +  3   struct el *p;                      3   struct el *p;
> +  4                                      4
> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
> lp) {
> +  7     if (p->key == key) {             7     if (p->key == key) {
> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> +                                        10       synchronize_rcu();
> + 10       kfree(p);                     11       kfree(p);
> + 11       return 1;                     12       return 1;
> + 12     }                               13     }
> + 13   }                                 14   }
> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> + 15   return 0;                         16   return 0;
> + 16 }                                   17 }
>
>  Either way, the differences are quite small.  Read-side locking moves
>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>
>
>  7.  FULL LIST OF RCU APIs
> +-------------------------
>
>  The RCU APIs are documented in docbook-format header comments in the
>  Linux-kernel source code, but it helps to have a full list of the
>  APIs, since there does not appear to be a way to categorize them
>  in docbook.  Here is the list, by category.
>
> -RCU list traversal:
> +RCU list traversal::
>
>         list_entry_rcu
>         list_first_entry_rcu
> @@ -854,7 +872,7 @@ RCU list traversal:
>         hlist_bl_first_rcu
>         hlist_bl_for_each_entry_rcu
>
> -RCU pointer/list update:
> +RCU pointer/list udate::
>
>         rcu_assign_pointer
>         list_add_rcu
> @@ -876,7 +894,9 @@ RCU pointer/list update:
>         hlist_bl_del_rcu
>         hlist_bl_set_first_rcu
>
> -RCU:   Critical sections       Grace period            Barrier
> +RCU::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock           synchronize_net         rcu_barrier
>         rcu_read_unlock         synchronize_rcu
> @@ -885,7 +905,9 @@ RCU:        Critical sections       Grace period
>       Barrier
>         rcu_dereference_check   kfree_rcu
>         rcu_dereference_protected
>
> -bh:    Critical sections       Grace period            Barrier
> +bh::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock_bh        call_rcu                rcu_barrier
>         rcu_read_unlock_bh      synchronize_rcu
> @@ -896,7 +918,9 @@ bh: Critical sections       Grace period
> Barrier
>         rcu_dereference_bh_protected
>         rcu_read_lock_bh_held
>
> -sched: Critical sections       Grace period            Barrier
> +sched::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock_sched     call_rcu                rcu_barrier
>         rcu_read_unlock_sched   synchronize_rcu
> @@ -910,7 +934,9 @@ sched:      Critical sections       Grace period
>       Barrier
>         rcu_read_lock_sched_held
>
>
> -SRCU:  Critical sections       Grace period            Barrier
> +SRCU::
> +
> +       Critical sections       Grace period            Barrier
>
>         srcu_read_lock          call_srcu               srcu_barrier
>         srcu_read_unlock        synchronize_srcu
> @@ -918,13 +944,14 @@ SRCU:     Critical sections       Grace period
>       Barrier
>         srcu_dereference_check
>         srcu_read_lock_held
>
> -SRCU:  Initialization/cleanup
> +SRCU: Initialization/cleanup::
> +
>         DEFINE_SRCU
>         DEFINE_STATIC_SRCU
>         init_srcu_struct
>         cleanup_srcu_struct
>
> -All:  lockdep-checked RCU-protected pointer access
> +All: lockdep-checked RCU-protected pointer access::
>
>         rcu_access_pointer
>         rcu_dereference_raw
> @@ -976,6 +1003,7 @@ the right tool for your job.
>
>
>  8.  ANSWERS TO QUICK QUIZZES
> +----------------------------
>
>  Quick Quiz #1: Why is this argument naive?  How could a deadlock
>                 occur when using this algorithm in a real-world Linux
>

Here, the formatting is not proper. In the rst file, the question should be
added in the next line after Quick Quiz #1. Currently, half of the question
appears in bold and the rest half does not.
Also, as followed in all the documents there should be a cross-reference to
the answer to this question. As this document is quite big having
references would be helpful.
The same applies to all other quick quiz questions in this document and in
the Answers section as well the questions do not appear properly, half in
bold text and half not bold.

Apart from this, the other added changes look good!

Thank you
Madhuparna

-- 
> 2.20.1
>
> _______________________________________________
> Linux-kernel-mentees mailing list
> Linux-kernel-mentees at lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
>
?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/attachments/20191102/abc26822/attachment-0001.html>

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-02  8:31 ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
@ 2019-11-02  8:31   ` madhuparnabhowmik04
  2019-11-02  8:31   ` Madhuparna Bhowmik
  2019-11-02 12:00   ` tranmanphong at gmail.com (Phong Tran)
  2 siblings, 0 replies; 23+ messages in thread
From: madhuparnabhowmik04 @ 2019-11-02  8:31 UTC (permalink / raw)


I reviewed this patch, and I have the following suggestions:

On Thu, Oct 31, 2019 at 5:04 AM Phong Tran <tranmanphong at gmail.com> wrote:

> Sync the format with current state of kernel documentation.
> This change base on rcu-dev branch
> what changed:
> - Format bullet lists
> - Add literal blocks
>
> Signed-off-by: Phong Tran <tranmanphong at gmail.com>
> ---
>  Documentation/RCU/index.rst                   |   1 +
>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>  2 files changed, 90 insertions(+), 61 deletions(-)
>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
>
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index 627128c230dc..b9b11481c727 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 3
>
>     arrayRCU
> +   whatisRCU
>     rcu
>     listRCU
>     NMI-RCU
> diff --git a/Documentation/RCU/whatisRCU.txt
> b/Documentation/RCU/whatisRCU.rst
> similarity index 91%
> rename from Documentation/RCU/whatisRCU.txt
> rename to Documentation/RCU/whatisRCU.rst
> index 58ba05c4d97f..70d0e4c21917 100644
> --- a/Documentation/RCU/whatisRCU.txt
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -1,15 +1,18 @@
> +.. _rcu_doc:
> +
>  What is RCU?  --  "Read, Copy, Update"
> +======================================
>
>  Please note that the "What is RCU?" LWN series is an excellent place
>  to start learning about RCU:
>
> -1.     What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> -2.     What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> -3.     RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> -4.     The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> -       2010 Big API Table           http://lwn.net/Articles/419086/
> -5.     The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> -       2014 Big API Table           http://lwn.net/Articles/609973/
> +| 1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> +| 2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> +| 3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> +| 4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> +|      2010 Big API Table           http://lwn.net/Articles/419086/
> +| 5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> +|      2014 Big API Table           http://lwn.net/Articles/609973/
>
>
Adding an external link here would be better.
like this :  `text <link URL>`_

 What is RCU?
> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>
>
>
There is a list of topics that are covered in this documentation.
Like this:

1. RCU OVERVIEW
2. WHAT IS RCU?S CORE API?
3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
...

 since this document is quite big adding cross-references to the above
would be helpful.


>  1.  RCU OVERVIEW
> +----------------
>
>  The basic idea behind RCU is to split updates into "removal" and
>  "reclamation" phases.  The removal phase removes references to data items
> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>
>
>  2.  WHAT IS RCU'S CORE API?
> +---------------------------
>
>  The core RCU API is quite small:
>
> @@ -166,7 +171,7 @@ synchronize_rcu()
>         read-side critical sections on all CPUs have completed.
>         Note that synchronize_rcu() will -not- necessarily wait for
>         any subsequent RCU read-side critical sections to complete.
> -       For example, consider the following sequence of events:
> +       For example, consider the following sequence of events::
>
>                  CPU 0                  CPU 1                 CPU 2
>              ----------------- ------------------------- ---------------
> @@ -248,13 +253,13 @@ rcu_dereference()
>
>         Common coding practice uses rcu_dereference() to copy an
>         RCU-protected pointer to a local variable, then dereferences
> -       this local variable, for example as follows:
> +       this local variable, for example as follows::
>
>                 p = rcu_dereference(head.next);
>                 return p->data;
>
>         However, in this case, one could just as easily combine these
> -       into one statement:
> +       into one statement::
>
>                 return rcu_dereference(head.next)->data;
>
> @@ -267,7 +272,7 @@ rcu_dereference()
>
>         Note that the value returned by rcu_dereference() is valid
>         only within the enclosing RCU read-side critical section [1].
> -       For example, the following is -not- legal:
> +       For example, the following is -not- legal::
>
>                 rcu_read_lock();
>                 p = rcu_dereference(head.next);
> @@ -315,6 +320,7 @@ rcu_dereference()
>
>  The following diagram shows how each API communicates among the
>  reader, updater, and reclaimer.
> +::
>
>
>             rcu_assign_pointer()
> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>
>
>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> +-----------------------------------------------
>
>  This section shows a simple use of the core RCU API to protect a
>  global pointer to a dynamically allocated structure.  More-typical
>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> +::
>
>         struct foo {
>                 int a;
> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>
>
>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> +--------------------------------------------
>
>  In the example above, foo_update_a() blocks until a grace period elapses.
>  This is quite simple, but in some cases one cannot afford to wait so
>  long -- there might be other high-priority work to be done.
>
>  In such cases, one uses call_rcu() rather than synchronize_rcu().
> -The call_rcu() API is as follows:
> +The call_rcu() API is as follows::
>
>         void call_rcu(struct rcu_head * head,
>                       void (*func)(struct rcu_head *head));
> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>  This function invokes func(head) after a grace period has elapsed.
>  This invocation might happen from either softirq or process context,
>  so the function is not permitted to block.  The foo struct needs to
> -have an rcu_head structure added, perhaps as follows:
> +have an rcu_head structure added, perhaps as follows::
>
>         struct foo {
>                 int a;
> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>                 struct rcu_head rcu;
>         };
>
> -The foo_update_a() function might then be written as follows:
> +The foo_update_a() function might then be written as follows::
>
>         /*
>          * Create a new struct foo that is the same as the one currently
> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> follows:
>                 call_rcu(&old_fp->rcu, foo_reclaim);
>         }
>
> -The foo_reclaim() function might appear as follows:
> +The foo_reclaim() function might appear as follows::
>
>         void foo_reclaim(struct rcu_head *rp)
>         {
> @@ -552,7 +561,7 @@ o   Use call_rcu() -after- removing a data element
> from an
>
>  If the callback for call_rcu() is not doing anything more than calling
>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> -to avoid having to write your own callback:
> +to avoid having to write your own callback::
>
>         kfree_rcu(old_fp, rcu);
>
> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> governing the use of RCU.
>
>
>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> +------------------------------------------------
>
>  One of the nice things about RCU is that it has extremely simple "toy"
>  implementations that are a good first step towards understanding the
> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> deadlock.
>  However, it is probably the easiest implementation to relate to, so is
>  a good starting point.
>
> -It is extremely simple:
> +It is extremely simple::
>
>         static DEFINE_RWLOCK(rcu_gp_mutex);
>
> @@ -614,7 +624,7 @@ It is extremely simple:
>
>  [You can ignore rcu_assign_pointer() and rcu_dereference() without missing
>  much.  But here are simplified versions anyway.  And whatever you do,
> -don't forget about them when submitting patches making use of RCU!]
> +don't forget about them when submitting patches making use of RCU!]::
>
>         #define rcu_assign_pointer(p, v) \
>         ({ \
> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that
> is based on
>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>  are the same as those shown in the preceding section, so they are omitted.
> +::
>
>         void rcu_read_lock(void) { }
>
> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU
> read-side
>
>
>  6.  ANALOGY WITH READER-WRITER LOCKING
> +--------------------------------------
>
>  Although RCU can be used in many different ways, a very common use of
>  RCU is analogous to reader-writer locking.  The following unified
>  diff shows how closely related RCU and reader-writer locking can be.
> +::
>
>         @@ -5,5 +5,5 @@ struct el {
>                 int data;
> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> locking can be.
>                 return 0;
>          }
>
> -Or, for those who prefer a side-by-side listing:
> +Or, for those who prefer a side-by-side listing::
>
>   1 struct el {                          1 struct el {
>   2   struct list_head list;             2   struct list_head list;
> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>   9 struct el head;                      9 struct el head;
>
> - 1 int search(long key, int *result)    1 int search(long key, int
> *result)
> - 2 {                                    2 {
> - 3   struct list_head *lp;              3   struct list_head *lp;
> - 4   struct el *p;                      4   struct el *p;
> - 5                                      5
> - 6   read_lock(&listmutex);             6   rcu_read_lock();
> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> - 8     if (p->key == key) {             8     if (p->key == key) {
> - 9       *result = p->data;             9       *result = p->data;
> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> -11       return 1;                     11       return 1;
> -12     }                               12     }
> -13   }                                 13   }
> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> -15   return 0;                         15   return 0;
> -16 }                                   16 }
> -
> - 1 int delete(long key)                 1 int delete(long key)
> - 2 {                                    2 {
> - 3   struct el *p;                      3   struct el *p;
> - 4                                      4
> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
> lp) {
> - 7     if (p->key == key) {             7     if (p->key == key) {
> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> -                                       10       synchronize_rcu();
> -10       kfree(p);                     11       kfree(p);
> -11       return 1;                     12       return 1;
> -12     }                               13     }
> -13   }                                 14   }
> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> -15   return 0;                         16   return 0;
> -16 }                                   17 }
> +::
> +
> +  1 int search(long key, int *result)    1 int search(long key, int
> *result)
> +  2 {                                    2 {
> +  3   struct list_head *lp;              3   struct list_head *lp;
> +  4   struct el *p;                      4   struct el *p;
> +  5                                      5
> +  6   read_lock(&listmutex);             6   rcu_read_lock();
> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> +  8     if (p->key == key) {             8     if (p->key == key) {
> +  9       *result = p->data;             9       *result = p->data;
> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> + 11       return 1;                     11       return 1;
> + 12     }                               12     }
> + 13   }                                 13   }
> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> + 15   return 0;                         15   return 0;
> + 16 }                                   16 }
> +
> +::
> +
> +  1 int delete(long key)                 1 int delete(long key)
> +  2 {                                    2 {
> +  3   struct el *p;                      3   struct el *p;
> +  4                                      4
> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
> lp) {
> +  7     if (p->key == key) {             7     if (p->key == key) {
> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> +                                        10       synchronize_rcu();
> + 10       kfree(p);                     11       kfree(p);
> + 11       return 1;                     12       return 1;
> + 12     }                               13     }
> + 13   }                                 14   }
> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> + 15   return 0;                         16   return 0;
> + 16 }                                   17 }
>
>  Either way, the differences are quite small.  Read-side locking moves
>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>
>
>  7.  FULL LIST OF RCU APIs
> +-------------------------
>
>  The RCU APIs are documented in docbook-format header comments in the
>  Linux-kernel source code, but it helps to have a full list of the
>  APIs, since there does not appear to be a way to categorize them
>  in docbook.  Here is the list, by category.
>
> -RCU list traversal:
> +RCU list traversal::
>
>         list_entry_rcu
>         list_first_entry_rcu
> @@ -854,7 +872,7 @@ RCU list traversal:
>         hlist_bl_first_rcu
>         hlist_bl_for_each_entry_rcu
>
> -RCU pointer/list update:
> +RCU pointer/list udate::
>
>         rcu_assign_pointer
>         list_add_rcu
> @@ -876,7 +894,9 @@ RCU pointer/list update:
>         hlist_bl_del_rcu
>         hlist_bl_set_first_rcu
>
> -RCU:   Critical sections       Grace period            Barrier
> +RCU::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock           synchronize_net         rcu_barrier
>         rcu_read_unlock         synchronize_rcu
> @@ -885,7 +905,9 @@ RCU:        Critical sections       Grace period
>       Barrier
>         rcu_dereference_check   kfree_rcu
>         rcu_dereference_protected
>
> -bh:    Critical sections       Grace period            Barrier
> +bh::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock_bh        call_rcu                rcu_barrier
>         rcu_read_unlock_bh      synchronize_rcu
> @@ -896,7 +918,9 @@ bh: Critical sections       Grace period
> Barrier
>         rcu_dereference_bh_protected
>         rcu_read_lock_bh_held
>
> -sched: Critical sections       Grace period            Barrier
> +sched::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock_sched     call_rcu                rcu_barrier
>         rcu_read_unlock_sched   synchronize_rcu
> @@ -910,7 +934,9 @@ sched:      Critical sections       Grace period
>       Barrier
>         rcu_read_lock_sched_held
>
>
> -SRCU:  Critical sections       Grace period            Barrier
> +SRCU::
> +
> +       Critical sections       Grace period            Barrier
>
>         srcu_read_lock          call_srcu               srcu_barrier
>         srcu_read_unlock        synchronize_srcu
> @@ -918,13 +944,14 @@ SRCU:     Critical sections       Grace period
>       Barrier
>         srcu_dereference_check
>         srcu_read_lock_held
>
> -SRCU:  Initialization/cleanup
> +SRCU: Initialization/cleanup::
> +
>         DEFINE_SRCU
>         DEFINE_STATIC_SRCU
>         init_srcu_struct
>         cleanup_srcu_struct
>
> -All:  lockdep-checked RCU-protected pointer access
> +All: lockdep-checked RCU-protected pointer access::
>
>         rcu_access_pointer
>         rcu_dereference_raw
> @@ -976,6 +1003,7 @@ the right tool for your job.
>
>
>  8.  ANSWERS TO QUICK QUIZZES
> +----------------------------
>
>  Quick Quiz #1: Why is this argument naive?  How could a deadlock
>                 occur when using this algorithm in a real-world Linux
>

Here, the formatting is not proper. In the rst file, the question should be
added in the next line after Quick Quiz #1. Currently, half of the question
appears in bold and the rest half does not.
Also, as followed in all the documents there should be a cross-reference to
the answer to this question. As this document is quite big having
references would be helpful.
The same applies to all other quick quiz questions in this document and in
the Answers section as well the questions do not appear properly, half in
bold text and half not bold.

Apart from this, the other added changes look good!

Thank you
Madhuparna

-- 
> 2.20.1
>
> _______________________________________________
> Linux-kernel-mentees mailing list
> Linux-kernel-mentees at lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
>
?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/attachments/20191102/abc26822/attachment-0001.html>

^ permalink raw reply	[flat|nested] 23+ messages in thread

* Re: [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-02  8:31 ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  2019-11-02  8:31   ` madhuparnabhowmik04
@ 2019-11-02  8:31   ` Madhuparna Bhowmik
  2019-11-02 12:00   ` tranmanphong at gmail.com (Phong Tran)
  2 siblings, 0 replies; 23+ messages in thread
From: Madhuparna Bhowmik @ 2019-11-02  8:31 UTC (permalink / raw)
  To: Phong Tran
  Cc: paulmck, corbet, linux-doc, jiangshanlai, josh, rostedt,
	linux-kernel, rcu, mathieu.desnoyers, Joel Fernandes,
	linux-kernel-mentees

[-- Attachment #1.1: Type: text/plain, Size: 18741 bytes --]

I reviewed this patch, and I have the following suggestions:

On Thu, Oct 31, 2019 at 5:04 AM Phong Tran <tranmanphong@gmail.com> wrote:

> Sync the format with current state of kernel documentation.
> This change base on rcu-dev branch
> what changed:
> - Format bullet lists
> - Add literal blocks
>
> Signed-off-by: Phong Tran <tranmanphong@gmail.com>
> ---
>  Documentation/RCU/index.rst                   |   1 +
>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>  2 files changed, 90 insertions(+), 61 deletions(-)
>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
>
> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
> index 627128c230dc..b9b11481c727 100644
> --- a/Documentation/RCU/index.rst
> +++ b/Documentation/RCU/index.rst
> @@ -8,6 +8,7 @@ RCU concepts
>     :maxdepth: 3
>
>     arrayRCU
> +   whatisRCU
>     rcu
>     listRCU
>     NMI-RCU
> diff --git a/Documentation/RCU/whatisRCU.txt
> b/Documentation/RCU/whatisRCU.rst
> similarity index 91%
> rename from Documentation/RCU/whatisRCU.txt
> rename to Documentation/RCU/whatisRCU.rst
> index 58ba05c4d97f..70d0e4c21917 100644
> --- a/Documentation/RCU/whatisRCU.txt
> +++ b/Documentation/RCU/whatisRCU.rst
> @@ -1,15 +1,18 @@
> +.. _rcu_doc:
> +
>  What is RCU?  --  "Read, Copy, Update"
> +======================================
>
>  Please note that the "What is RCU?" LWN series is an excellent place
>  to start learning about RCU:
>
> -1.     What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> -2.     What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> -3.     RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> -4.     The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> -       2010 Big API Table           http://lwn.net/Articles/419086/
> -5.     The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> -       2014 Big API Table           http://lwn.net/Articles/609973/
> +| 1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
> +| 2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
> +| 3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
> +| 4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
> +|      2010 Big API Table           http://lwn.net/Articles/419086/
> +| 5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
> +|      2014 Big API Table           http://lwn.net/Articles/609973/
>
>
Adding an external link here would be better.
like this :  `text <link URL>`_

 What is RCU?
> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>
>
>
There is a list of topics that are covered in this documentation.
Like this:

1. RCU OVERVIEW
2. WHAT IS RCU’S CORE API?
3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
...

 since this document is quite big adding cross-references to the above
would be helpful.


>  1.  RCU OVERVIEW
> +----------------
>
>  The basic idea behind RCU is to split updates into "removal" and
>  "reclamation" phases.  The removal phase removes references to data items
> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>
>
>  2.  WHAT IS RCU'S CORE API?
> +---------------------------
>
>  The core RCU API is quite small:
>
> @@ -166,7 +171,7 @@ synchronize_rcu()
>         read-side critical sections on all CPUs have completed.
>         Note that synchronize_rcu() will -not- necessarily wait for
>         any subsequent RCU read-side critical sections to complete.
> -       For example, consider the following sequence of events:
> +       For example, consider the following sequence of events::
>
>                  CPU 0                  CPU 1                 CPU 2
>              ----------------- ------------------------- ---------------
> @@ -248,13 +253,13 @@ rcu_dereference()
>
>         Common coding practice uses rcu_dereference() to copy an
>         RCU-protected pointer to a local variable, then dereferences
> -       this local variable, for example as follows:
> +       this local variable, for example as follows::
>
>                 p = rcu_dereference(head.next);
>                 return p->data;
>
>         However, in this case, one could just as easily combine these
> -       into one statement:
> +       into one statement::
>
>                 return rcu_dereference(head.next)->data;
>
> @@ -267,7 +272,7 @@ rcu_dereference()
>
>         Note that the value returned by rcu_dereference() is valid
>         only within the enclosing RCU read-side critical section [1].
> -       For example, the following is -not- legal:
> +       For example, the following is -not- legal::
>
>                 rcu_read_lock();
>                 p = rcu_dereference(head.next);
> @@ -315,6 +320,7 @@ rcu_dereference()
>
>  The following diagram shows how each API communicates among the
>  reader, updater, and reclaimer.
> +::
>
>
>             rcu_assign_pointer()
> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>
>
>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> +-----------------------------------------------
>
>  This section shows a simple use of the core RCU API to protect a
>  global pointer to a dynamically allocated structure.  More-typical
>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
> +::
>
>         struct foo {
>                 int a;
> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>
>
>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> +--------------------------------------------
>
>  In the example above, foo_update_a() blocks until a grace period elapses.
>  This is quite simple, but in some cases one cannot afford to wait so
>  long -- there might be other high-priority work to be done.
>
>  In such cases, one uses call_rcu() rather than synchronize_rcu().
> -The call_rcu() API is as follows:
> +The call_rcu() API is as follows::
>
>         void call_rcu(struct rcu_head * head,
>                       void (*func)(struct rcu_head *head));
> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>  This function invokes func(head) after a grace period has elapsed.
>  This invocation might happen from either softirq or process context,
>  so the function is not permitted to block.  The foo struct needs to
> -have an rcu_head structure added, perhaps as follows:
> +have an rcu_head structure added, perhaps as follows::
>
>         struct foo {
>                 int a;
> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>                 struct rcu_head rcu;
>         };
>
> -The foo_update_a() function might then be written as follows:
> +The foo_update_a() function might then be written as follows::
>
>         /*
>          * Create a new struct foo that is the same as the one currently
> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
> follows:
>                 call_rcu(&old_fp->rcu, foo_reclaim);
>         }
>
> -The foo_reclaim() function might appear as follows:
> +The foo_reclaim() function might appear as follows::
>
>         void foo_reclaim(struct rcu_head *rp)
>         {
> @@ -552,7 +561,7 @@ o   Use call_rcu() -after- removing a data element
> from an
>
>  If the callback for call_rcu() is not doing anything more than calling
>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
> -to avoid having to write your own callback:
> +to avoid having to write your own callback::
>
>         kfree_rcu(old_fp, rcu);
>
> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
> governing the use of RCU.
>
>
>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
> +------------------------------------------------
>
>  One of the nice things about RCU is that it has extremely simple "toy"
>  implementations that are a good first step towards understanding the
> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
> deadlock.
>  However, it is probably the easiest implementation to relate to, so is
>  a good starting point.
>
> -It is extremely simple:
> +It is extremely simple::
>
>         static DEFINE_RWLOCK(rcu_gp_mutex);
>
> @@ -614,7 +624,7 @@ It is extremely simple:
>
>  [You can ignore rcu_assign_pointer() and rcu_dereference() without missing
>  much.  But here are simplified versions anyway.  And whatever you do,
> -don't forget about them when submitting patches making use of RCU!]
> +don't forget about them when submitting patches making use of RCU!]::
>
>         #define rcu_assign_pointer(p, v) \
>         ({ \
> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that
> is based on
>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>  are the same as those shown in the preceding section, so they are omitted.
> +::
>
>         void rcu_read_lock(void) { }
>
> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU
> read-side
>
>
>  6.  ANALOGY WITH READER-WRITER LOCKING
> +--------------------------------------
>
>  Although RCU can be used in many different ways, a very common use of
>  RCU is analogous to reader-writer locking.  The following unified
>  diff shows how closely related RCU and reader-writer locking can be.
> +::
>
>         @@ -5,5 +5,5 @@ struct el {
>                 int data;
> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
> locking can be.
>                 return 0;
>          }
>
> -Or, for those who prefer a side-by-side listing:
> +Or, for those who prefer a side-by-side listing::
>
>   1 struct el {                          1 struct el {
>   2   struct list_head list;             2   struct list_head list;
> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>   9 struct el head;                      9 struct el head;
>
> - 1 int search(long key, int *result)    1 int search(long key, int
> *result)
> - 2 {                                    2 {
> - 3   struct list_head *lp;              3   struct list_head *lp;
> - 4   struct el *p;                      4   struct el *p;
> - 5                                      5
> - 6   read_lock(&listmutex);             6   rcu_read_lock();
> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> - 8     if (p->key == key) {             8     if (p->key == key) {
> - 9       *result = p->data;             9       *result = p->data;
> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
> -11       return 1;                     11       return 1;
> -12     }                               12     }
> -13   }                                 13   }
> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
> -15   return 0;                         15   return 0;
> -16 }                                   16 }
> -
> - 1 int delete(long key)                 1 int delete(long key)
> - 2 {                                    2 {
> - 3   struct el *p;                      3   struct el *p;
> - 4                                      4
> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
> lp) {
> - 7     if (p->key == key) {             7     if (p->key == key) {
> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> -                                       10       synchronize_rcu();
> -10       kfree(p);                     11       kfree(p);
> -11       return 1;                     12       return 1;
> -12     }                               13     }
> -13   }                                 14   }
> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> -15   return 0;                         16   return 0;
> -16 }                                   17 }
> +::
> +
> +  1 int search(long key, int *result)    1 int search(long key, int
> *result)
> +  2 {                                    2 {
> +  3   struct list_head *lp;              3   struct list_head *lp;
> +  4   struct el *p;                      4   struct el *p;
> +  5                                      5
> +  6   read_lock(&listmutex);             6   rcu_read_lock();
> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
> head, lp) {
> +  8     if (p->key == key) {             8     if (p->key == key) {
> +  9       *result = p->data;             9       *result = p->data;
> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
> + 11       return 1;                     11       return 1;
> + 12     }                               12     }
> + 13   }                                 13   }
> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
> + 15   return 0;                         15   return 0;
> + 16 }                                   16 }
> +
> +::
> +
> +  1 int delete(long key)                 1 int delete(long key)
> +  2 {                                    2 {
> +  3   struct el *p;                      3   struct el *p;
> +  4                                      4
> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
> lp) {
> +  7     if (p->key == key) {             7     if (p->key == key) {
> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
> +                                        10       synchronize_rcu();
> + 10       kfree(p);                     11       kfree(p);
> + 11       return 1;                     12       return 1;
> + 12     }                               13     }
> + 13   }                                 14   }
> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
> + 15   return 0;                         16   return 0;
> + 16 }                                   17 }
>
>  Either way, the differences are quite small.  Read-side locking moves
>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>
>
>  7.  FULL LIST OF RCU APIs
> +-------------------------
>
>  The RCU APIs are documented in docbook-format header comments in the
>  Linux-kernel source code, but it helps to have a full list of the
>  APIs, since there does not appear to be a way to categorize them
>  in docbook.  Here is the list, by category.
>
> -RCU list traversal:
> +RCU list traversal::
>
>         list_entry_rcu
>         list_first_entry_rcu
> @@ -854,7 +872,7 @@ RCU list traversal:
>         hlist_bl_first_rcu
>         hlist_bl_for_each_entry_rcu
>
> -RCU pointer/list update:
> +RCU pointer/list udate::
>
>         rcu_assign_pointer
>         list_add_rcu
> @@ -876,7 +894,9 @@ RCU pointer/list update:
>         hlist_bl_del_rcu
>         hlist_bl_set_first_rcu
>
> -RCU:   Critical sections       Grace period            Barrier
> +RCU::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock           synchronize_net         rcu_barrier
>         rcu_read_unlock         synchronize_rcu
> @@ -885,7 +905,9 @@ RCU:        Critical sections       Grace period
>       Barrier
>         rcu_dereference_check   kfree_rcu
>         rcu_dereference_protected
>
> -bh:    Critical sections       Grace period            Barrier
> +bh::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock_bh        call_rcu                rcu_barrier
>         rcu_read_unlock_bh      synchronize_rcu
> @@ -896,7 +918,9 @@ bh: Critical sections       Grace period
> Barrier
>         rcu_dereference_bh_protected
>         rcu_read_lock_bh_held
>
> -sched: Critical sections       Grace period            Barrier
> +sched::
> +
> +       Critical sections       Grace period            Barrier
>
>         rcu_read_lock_sched     call_rcu                rcu_barrier
>         rcu_read_unlock_sched   synchronize_rcu
> @@ -910,7 +934,9 @@ sched:      Critical sections       Grace period
>       Barrier
>         rcu_read_lock_sched_held
>
>
> -SRCU:  Critical sections       Grace period            Barrier
> +SRCU::
> +
> +       Critical sections       Grace period            Barrier
>
>         srcu_read_lock          call_srcu               srcu_barrier
>         srcu_read_unlock        synchronize_srcu
> @@ -918,13 +944,14 @@ SRCU:     Critical sections       Grace period
>       Barrier
>         srcu_dereference_check
>         srcu_read_lock_held
>
> -SRCU:  Initialization/cleanup
> +SRCU: Initialization/cleanup::
> +
>         DEFINE_SRCU
>         DEFINE_STATIC_SRCU
>         init_srcu_struct
>         cleanup_srcu_struct
>
> -All:  lockdep-checked RCU-protected pointer access
> +All: lockdep-checked RCU-protected pointer access::
>
>         rcu_access_pointer
>         rcu_dereference_raw
> @@ -976,6 +1003,7 @@ the right tool for your job.
>
>
>  8.  ANSWERS TO QUICK QUIZZES
> +----------------------------
>
>  Quick Quiz #1: Why is this argument naive?  How could a deadlock
>                 occur when using this algorithm in a real-world Linux
>

Here, the formatting is not proper. In the rst file, the question should be
added in the next line after Quick Quiz #1. Currently, half of the question
appears in bold and the rest half does not.
Also, as followed in all the documents there should be a cross-reference to
the answer to this question. As this document is quite big having
references would be helpful.
The same applies to all other quick quiz questions in this document and in
the Answers section as well the questions do not appear properly, half in
bold text and half not bold.

Apart from this, the other added changes look good!

Thank you
Madhuparna

-- 
> 2.20.1
>
> _______________________________________________
> Linux-kernel-mentees mailing list
> Linux-kernel-mentees@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
>
[-- Attachment #1.2: Type: text/html, Size: 24835 bytes --]

<div dir="ltr"><div>I reviewed this patch, and I have the following suggestions:</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Oct 31, 2019 at 5:04 AM Phong Tran &lt;<a href="mailto:tranmanphong@gmail.com">tranmanphong@gmail.com</a>&gt; wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Sync the format with current state of kernel documentation.<br>
This change base on rcu-dev branch<br>
what changed:<br>
- Format bullet lists<br>
- Add literal blocks<br>
<br>
Signed-off-by: Phong Tran &lt;<a href="mailto:tranmanphong@gmail.com" target="_blank">tranmanphong@gmail.com</a>&gt;<br>
---<br>
 Documentation/RCU/index.rst                   |   1 +<br>
 .../RCU/{whatisRCU.txt =&gt; whatisRCU.rst}      | 150 +++++++++++-------<br>
 2 files changed, 90 insertions(+), 61 deletions(-)<br>
 rename Documentation/RCU/{whatisRCU.txt =&gt; whatisRCU.rst} (91%)<br>
<br>
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst<br>
index 627128c230dc..b9b11481c727 100644<br>
--- a/Documentation/RCU/index.rst<br>
+++ b/Documentation/RCU/index.rst<br>
@@ -8,6 +8,7 @@ RCU concepts<br>
    :maxdepth: 3<br>
<br>
    arrayRCU<br>
+   whatisRCU<br>
    rcu<br>
    listRCU<br>
    NMI-RCU<br>
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst<br>
similarity index 91%<br>
rename from Documentation/RCU/whatisRCU.txt<br>
rename to Documentation/RCU/whatisRCU.rst<br>
index 58ba05c4d97f..70d0e4c21917 100644<br>
--- a/Documentation/RCU/whatisRCU.txt<br>
+++ b/Documentation/RCU/whatisRCU.rst<br>
@@ -1,15 +1,18 @@<br>
+.. _rcu_doc:<br>
+<br>
 What is RCU?  --  &quot;Read, Copy, Update&quot;<br>
+======================================<br>
<br>
 Please note that the &quot;What is RCU?&quot; LWN series is an excellent place<br>
 to start learning about RCU:<br>
<br>
-1.     What is RCU, Fundamentally?  <a href="http://lwn.net/Articles/262464/" rel="noreferrer" target="_blank">http://lwn.net/Articles/262464/</a><br>
-2.     What is RCU? Part 2: Usage   <a href="http://lwn.net/Articles/263130/" rel="noreferrer" target="_blank">http://lwn.net/Articles/263130/</a><br>
-3.     RCU part 3: the RCU API      <a href="http://lwn.net/Articles/264090/" rel="noreferrer" target="_blank">http://lwn.net/Articles/264090/</a><br>
-4.     The RCU API, 2010 Edition    <a href="http://lwn.net/Articles/418853/" rel="noreferrer" target="_blank">http://lwn.net/Articles/418853/</a><br>
-       2010 Big API Table           <a href="http://lwn.net/Articles/419086/" rel="noreferrer" target="_blank">http://lwn.net/Articles/419086/</a><br>
-5.     The RCU API, 2014 Edition    <a href="http://lwn.net/Articles/609904/" rel="noreferrer" target="_blank">http://lwn.net/Articles/609904/</a><br>
-       2014 Big API Table           <a href="http://lwn.net/Articles/609973/" rel="noreferrer" target="_blank">http://lwn.net/Articles/609973/</a><br>
+| 1.   What is RCU, Fundamentally?  <a href="http://lwn.net/Articles/262464/" rel="noreferrer" target="_blank">http://lwn.net/Articles/262464/</a><br>
+| 2.   What is RCU? Part 2: Usage   <a href="http://lwn.net/Articles/263130/" rel="noreferrer" target="_blank">http://lwn.net/Articles/263130/</a><br>
+| 3.   RCU part 3: the RCU API      <a href="http://lwn.net/Articles/264090/" rel="noreferrer" target="_blank">http://lwn.net/Articles/264090/</a><br>
+| 4.   The RCU API, 2010 Edition    <a href="http://lwn.net/Articles/418853/" rel="noreferrer" target="_blank">http://lwn.net/Articles/418853/</a><br>
+|      2010 Big API Table           <a href="http://lwn.net/Articles/419086/" rel="noreferrer" target="_blank">http://lwn.net/Articles/419086/</a><br>
+| 5.   The RCU API, 2014 Edition    <a href="http://lwn.net/Articles/609904/" rel="noreferrer" target="_blank">http://lwn.net/Articles/609904/</a><br>
+|      2014 Big API Table           <a href="http://lwn.net/Articles/609973/" rel="noreferrer" target="_blank">http://lwn.net/Articles/609973/</a><br><br></blockquote><div><br></div><div>Adding an external link here would be better.</div><div>like this :  <span class="gmail-s" style="font-family:Menlo,Monaco,Consolas,&quot;Courier New&quot;,monospace;font-size:13px;box-sizing:border-box;color:rgb(64,112,160)">`text </span><span class="gmail-si" style="font-family:Menlo,Monaco,Consolas,&quot;Courier New&quot;,monospace;font-size:13px;box-sizing:border-box;color:rgb(112,160,208);font-style:italic">&lt;link URL&gt;</span><span class="gmail-s" style="font-family:Menlo,Monaco,Consolas,&quot;Courier New&quot;,monospace;font-size:13px;box-sizing:border-box;color:rgb(64,112,160)">`_</span> </div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
 What is RCU?<br>
@@ -51,6 +54,7 @@ never need this document anyway.  ;-)<br>
<br>
<br></blockquote><div><br></div><div>There is a list of topics that are covered in this documentation.</div><div>Like this:</div><div><br></div><div>1. RCU OVERVIEW<br>2. WHAT IS RCU’S CORE API?<br>3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?<br>4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?<br></div><div>...</div><div><br></div><div> since this document is quite big adding cross-references to the above would be helpful.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
 1.  RCU OVERVIEW<br>
+----------------<br>
<br>
 The basic idea behind RCU is to split updates into &quot;removal&quot; and<br>
 &quot;reclamation&quot; phases.  The removal phase removes references to data items<br>
@@ -118,6 +122,7 @@ Read on to learn about how RCU&#39;s API makes this easy.<br>
<br>
<br>
 2.  WHAT IS RCU&#39;S CORE API?<br>
+---------------------------<br>
<br>
 The core RCU API is quite small:<br>
<br>
@@ -166,7 +171,7 @@ synchronize_rcu()<br>
        read-side critical sections on all CPUs have completed.<br>
        Note that synchronize_rcu() will -not- necessarily wait for<br>
        any subsequent RCU read-side critical sections to complete.<br>
-       For example, consider the following sequence of events:<br>
+       For example, consider the following sequence of events::<br>
<br>
                 CPU 0                  CPU 1                 CPU 2<br>
             ----------------- ------------------------- ---------------<br>
@@ -248,13 +253,13 @@ rcu_dereference()<br>
<br>
        Common coding practice uses rcu_dereference() to copy an<br>
        RCU-protected pointer to a local variable, then dereferences<br>
-       this local variable, for example as follows:<br>
+       this local variable, for example as follows::<br>
<br>
                p = rcu_dereference(head.next);<br>
                return p-&gt;data;<br>
<br>
        However, in this case, one could just as easily combine these<br>
-       into one statement:<br>
+       into one statement::<br>
<br>
                return rcu_dereference(head.next)-&gt;data;<br>
<br>
@@ -267,7 +272,7 @@ rcu_dereference()<br>
<br>
        Note that the value returned by rcu_dereference() is valid<br>
        only within the enclosing RCU read-side critical section [1].<br>
-       For example, the following is -not- legal:<br>
+       For example, the following is -not- legal::<br>
<br>
                rcu_read_lock();<br>
                p = rcu_dereference(head.next);<br>
@@ -315,6 +320,7 @@ rcu_dereference()<br>
<br>
 The following diagram shows how each API communicates among the<br>
 reader, updater, and reclaimer.<br>
+::<br>
<br>
<br>
            rcu_assign_pointer()<br>
@@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.<br>
<br>
<br>
 3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?<br>
+-----------------------------------------------<br>
<br>
 This section shows a simple use of the core RCU API to protect a<br>
 global pointer to a dynamically allocated structure.  More-typical<br>
 uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.<br>
+::<br>
<br>
        struct foo {<br>
                int a;<br>
@@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.<br>
<br>
<br>
 4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?<br>
+--------------------------------------------<br>
<br>
 In the example above, foo_update_a() blocks until a grace period elapses.<br>
 This is quite simple, but in some cases one cannot afford to wait so<br>
 long -- there might be other high-priority work to be done.<br>
<br>
 In such cases, one uses call_rcu() rather than synchronize_rcu().<br>
-The call_rcu() API is as follows:<br>
+The call_rcu() API is as follows::<br>
<br>
        void call_rcu(struct rcu_head * head,<br>
                      void (*func)(struct rcu_head *head));<br>
@@ -481,7 +490,7 @@ The call_rcu() API is as follows:<br>
 This function invokes func(head) after a grace period has elapsed.<br>
 This invocation might happen from either softirq or process context,<br>
 so the function is not permitted to block.  The foo struct needs to<br>
-have an rcu_head structure added, perhaps as follows:<br>
+have an rcu_head structure added, perhaps as follows::<br>
<br>
        struct foo {<br>
                int a;<br>
@@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:<br>
                struct rcu_head rcu;<br>
        };<br>
<br>
-The foo_update_a() function might then be written as follows:<br>
+The foo_update_a() function might then be written as follows::<br>
<br>
        /*<br>
         * Create a new struct foo that is the same as the one currently<br>
@@ -520,7 +529,7 @@ The foo_update_a() function might then be written as follows:<br>
                call_rcu(&amp;old_fp-&gt;rcu, foo_reclaim);<br>
        }<br>
<br>
-The foo_reclaim() function might appear as follows:<br>
+The foo_reclaim() function might appear as follows::<br>
<br>
        void foo_reclaim(struct rcu_head *rp)<br>
        {<br>
@@ -552,7 +561,7 @@ o   Use call_rcu() -after- removing a data element from an<br>
<br>
 If the callback for call_rcu() is not doing anything more than calling<br>
 kfree() on the structure, you can use kfree_rcu() instead of call_rcu()<br>
-to avoid having to write your own callback:<br>
+to avoid having to write your own callback::<br>
<br>
        kfree_rcu(old_fp, rcu);<br>
<br>
@@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules governing the use of RCU.<br>
<br>
<br>
 5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?<br>
+------------------------------------------------<br>
<br>
 One of the nice things about RCU is that it has extremely simple &quot;toy&quot;<br>
 implementations that are a good first step towards understanding the<br>
@@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can deadlock.<br>
 However, it is probably the easiest implementation to relate to, so is<br>
 a good starting point.<br>
<br>
-It is extremely simple:<br>
+It is extremely simple::<br>
<br>
        static DEFINE_RWLOCK(rcu_gp_mutex);<br>
<br>
@@ -614,7 +624,7 @@ It is extremely simple:<br>
<br>
 [You can ignore rcu_assign_pointer() and rcu_dereference() without missing<br>
 much.  But here are simplified versions anyway.  And whatever you do,<br>
-don&#39;t forget about them when submitting patches making use of RCU!]<br>
+don&#39;t forget about them when submitting patches making use of RCU!]::<br>
<br>
        #define rcu_assign_pointer(p, v) \<br>
        ({ \<br>
@@ -659,6 +669,7 @@ This section presents a &quot;toy&quot; RCU implementation that is based on<br>
 on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT<br>
 kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()<br>
 are the same as those shown in the preceding section, so they are omitted.<br>
+::<br>
<br>
        void rcu_read_lock(void) { }<br>
<br>
@@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU read-side<br>
<br>
<br>
 6.  ANALOGY WITH READER-WRITER LOCKING<br>
+--------------------------------------<br>
<br>
 Although RCU can be used in many different ways, a very common use of<br>
 RCU is analogous to reader-writer locking.  The following unified<br>
 diff shows how closely related RCU and reader-writer locking can be.<br>
+::<br>
<br>
        @@ -5,5 +5,5 @@ struct el {<br>
                int data;<br>
@@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer locking can be.<br>
                return 0;<br>
         }<br>
<br>
-Or, for those who prefer a side-by-side listing:<br>
+Or, for those who prefer a side-by-side listing::<br>
<br>
  1 struct el {                          1 struct el {<br>
  2   struct list_head list;             2   struct list_head list;<br>
@@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:<br>
  8 rwlock_t listmutex;                  8 spinlock_t listmutex;<br>
  9 struct el head;                      9 struct el head;<br>
<br>
- 1 int search(long key, int *result)    1 int search(long key, int *result)<br>
- 2 {                                    2 {<br>
- 3   struct list_head *lp;              3   struct list_head *lp;<br>
- 4   struct el *p;                      4   struct el *p;<br>
- 5                                      5<br>
- 6   read_lock(&amp;listmutex);             6   rcu_read_lock();<br>
- 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {<br>
- 8     if (p-&gt;key == key) {             8     if (p-&gt;key == key) {<br>
- 9       *result = p-&gt;data;             9       *result = p-&gt;data;<br>
-10       read_unlock(&amp;listmutex);      10       rcu_read_unlock();<br>
-11       return 1;                     11       return 1;<br>
-12     }                               12     }<br>
-13   }                                 13   }<br>
-14   read_unlock(&amp;listmutex);          14   rcu_read_unlock();<br>
-15   return 0;                         15   return 0;<br>
-16 }                                   16 }<br>
-<br>
- 1 int delete(long key)                 1 int delete(long key)<br>
- 2 {                                    2 {<br>
- 3   struct el *p;                      3   struct el *p;<br>
- 4                                      4<br>
- 5   write_lock(&amp;listmutex);            5   spin_lock(&amp;listmutex);<br>
- 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {<br>
- 7     if (p-&gt;key == key) {             7     if (p-&gt;key == key) {<br>
- 8       list_del(&amp;p-&gt;list);            8       list_del_rcu(&amp;p-&gt;list);<br>
- 9       write_unlock(&amp;listmutex);      9       spin_unlock(&amp;listmutex);<br>
-                                       10       synchronize_rcu();<br>
-10       kfree(p);                     11       kfree(p);<br>
-11       return 1;                     12       return 1;<br>
-12     }                               13     }<br>
-13   }                                 14   }<br>
-14   write_unlock(&amp;listmutex);         15   spin_unlock(&amp;listmutex);<br>
-15   return 0;                         16   return 0;<br>
-16 }                                   17 }<br>
+::<br>
+<br>
+  1 int search(long key, int *result)    1 int search(long key, int *result)<br>
+  2 {                                    2 {<br>
+  3   struct list_head *lp;              3   struct list_head *lp;<br>
+  4   struct el *p;                      4   struct el *p;<br>
+  5                                      5<br>
+  6   read_lock(&amp;listmutex);             6   rcu_read_lock();<br>
+  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {<br>
+  8     if (p-&gt;key == key) {             8     if (p-&gt;key == key) {<br>
+  9       *result = p-&gt;data;             9       *result = p-&gt;data;<br>
+ 10       read_unlock(&amp;listmutex);      10       rcu_read_unlock();<br>
+ 11       return 1;                     11       return 1;<br>
+ 12     }                               12     }<br>
+ 13   }                                 13   }<br>
+ 14   read_unlock(&amp;listmutex);          14   rcu_read_unlock();<br>
+ 15   return 0;                         15   return 0;<br>
+ 16 }                                   16 }<br>
+<br>
+::<br>
+<br>
+  1 int delete(long key)                 1 int delete(long key)<br>
+  2 {                                    2 {<br>
+  3   struct el *p;                      3   struct el *p;<br>
+  4                                      4<br>
+  5   write_lock(&amp;listmutex);            5   spin_lock(&amp;listmutex);<br>
+  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {<br>
+  7     if (p-&gt;key == key) {             7     if (p-&gt;key == key) {<br>
+  8       list_del(&amp;p-&gt;list);            8       list_del_rcu(&amp;p-&gt;list);<br>
+  9       write_unlock(&amp;listmutex);      9       spin_unlock(&amp;listmutex);<br>
+                                        10       synchronize_rcu();<br>
+ 10       kfree(p);                     11       kfree(p);<br>
+ 11       return 1;                     12       return 1;<br>
+ 12     }                               13     }<br>
+ 13   }                                 14   }<br>
+ 14   write_unlock(&amp;listmutex);         15   spin_unlock(&amp;listmutex);<br>
+ 15   return 0;                         16   return 0;<br>
+ 16 }                                   17 }<br>
<br>
 Either way, the differences are quite small.  Read-side locking moves<br>
 to rcu_read_lock() and rcu_read_unlock, update-side locking moves from<br>
@@ -827,13 +844,14 @@ be used in place of synchronize_rcu().<br>
<br>
<br>
 7.  FULL LIST OF RCU APIs<br>
+-------------------------<br>
<br>
 The RCU APIs are documented in docbook-format header comments in the<br>
 Linux-kernel source code, but it helps to have a full list of the<br>
 APIs, since there does not appear to be a way to categorize them<br>
 in docbook.  Here is the list, by category.<br>
<br>
-RCU list traversal:<br>
+RCU list traversal::<br>
<br>
        list_entry_rcu<br>
        list_first_entry_rcu<br>
@@ -854,7 +872,7 @@ RCU list traversal:<br>
        hlist_bl_first_rcu<br>
        hlist_bl_for_each_entry_rcu<br>
<br>
-RCU pointer/list update:<br>
+RCU pointer/list udate::<br>
<br>
        rcu_assign_pointer<br>
        list_add_rcu<br>
@@ -876,7 +894,9 @@ RCU pointer/list update:<br>
        hlist_bl_del_rcu<br>
        hlist_bl_set_first_rcu<br>
<br>
-RCU:   Critical sections       Grace period            Barrier<br>
+RCU::<br>
+<br>
+       Critical sections       Grace period            Barrier<br>
<br>
        rcu_read_lock           synchronize_net         rcu_barrier<br>
        rcu_read_unlock         synchronize_rcu<br>
@@ -885,7 +905,9 @@ RCU:        Critical sections       Grace period            Barrier<br>
        rcu_dereference_check   kfree_rcu<br>
        rcu_dereference_protected<br>
<br>
-bh:    Critical sections       Grace period            Barrier<br>
+bh::<br>
+<br>
+       Critical sections       Grace period            Barrier<br>
<br>
        rcu_read_lock_bh        call_rcu                rcu_barrier<br>
        rcu_read_unlock_bh      synchronize_rcu<br>
@@ -896,7 +918,9 @@ bh: Critical sections       Grace period            Barrier<br>
        rcu_dereference_bh_protected<br>
        rcu_read_lock_bh_held<br>
<br>
-sched: Critical sections       Grace period            Barrier<br>
+sched::<br>
+<br>
+       Critical sections       Grace period            Barrier<br>
<br>
        rcu_read_lock_sched     call_rcu                rcu_barrier<br>
        rcu_read_unlock_sched   synchronize_rcu<br>
@@ -910,7 +934,9 @@ sched:      Critical sections       Grace period            Barrier<br>
        rcu_read_lock_sched_held<br>
<br>
<br>
-SRCU:  Critical sections       Grace period            Barrier<br>
+SRCU::<br>
+<br>
+       Critical sections       Grace period            Barrier<br>
<br>
        srcu_read_lock          call_srcu               srcu_barrier<br>
        srcu_read_unlock        synchronize_srcu<br>
@@ -918,13 +944,14 @@ SRCU:     Critical sections       Grace period            Barrier<br>
        srcu_dereference_check<br>
        srcu_read_lock_held<br>
<br>
-SRCU:  Initialization/cleanup<br>
+SRCU: Initialization/cleanup::<br>
+<br>
        DEFINE_SRCU<br>
        DEFINE_STATIC_SRCU<br>
        init_srcu_struct<br>
        cleanup_srcu_struct<br>
<br>
-All:  lockdep-checked RCU-protected pointer access<br>
+All: lockdep-checked RCU-protected pointer access::<br>
<br>
        rcu_access_pointer<br>
        rcu_dereference_raw<br>
@@ -976,6 +1003,7 @@ the right tool for your job.<br>
<br>
<br>
 8.  ANSWERS TO QUICK QUIZZES<br>
+----------------------------<br>
<br>
 Quick Quiz #1: Why is this argument naive?  How could a deadlock<br>
                occur when using this algorithm in a real-world Linux<br></blockquote><div><br></div><div>Here, the formatting is not proper. In the rst file, the question should be added in the next line after Quick Quiz #1. Currently, half of the question appears in bold and the rest half does not.</div><div>Also, as followed in all the documents there should be a cross-reference to the answer to this question. As this document is quite big having references would be helpful.</div><div>The same applies to all other quick quiz questions in this document and in the Answers section as well the questions do not appear properly, half in bold text and half not bold.</div><div><br></div><div>Apart from this, the other added changes look good!</div><div><br></div><div>Thank you</div><div>Madhuparna</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
-- <br>
2.20.1<br>
<br>
_______________________________________________<br>
Linux-kernel-mentees mailing list<br>
<a href="mailto:Linux-kernel-mentees@lists.linuxfoundation.org" target="_blank">Linux-kernel-mentees@lists.linuxfoundation.org</a><br>
<a href="https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees" rel="noreferrer" target="_blank">https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees</a><br>
</blockquote></div></div><div hspace="streak-pt-mark" style="max-height:1px"><img alt="" style="width:0px;max-height:0px;overflow:hidden" src="https://mailfoogae.appspot.com/t?sender=abWFkaHVwYXJuYWJob3dtaWswNEBnbWFpbC5jb20%3D&amp;type=zerocontent&amp;guid=8fec4e47-6422-4486-a303-a30685f7265d"><font color="#ffffff" size="1">ᐧ</font></div>

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-02  8:31 ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
  2019-11-02  8:31   ` madhuparnabhowmik04
  2019-11-02  8:31   ` Madhuparna Bhowmik
@ 2019-11-02 12:00   ` tranmanphong at gmail.com (Phong Tran)
  2019-11-02 12:00     ` Phong Tran
  2019-11-02 12:00     ` tranmanphong
  2 siblings, 2 replies; 23+ messages in thread
From: tranmanphong at gmail.com (Phong Tran) @ 2019-11-02 12:00 UTC (permalink / raw)


On Sat, Nov 2, 2019 at 3:31 PM Madhuparna Bhowmik <
madhuparnabhowmik04 at gmail.com> wrote:

> I reviewed this patch, and I have the following suggestions:
>
> Thank for feedback. I did some change adding the cross-ref. patch sent
also apply in rcu-dev branch.

https://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/2019-November/001019.html

Regards,
Phong.

> On Thu, Oct 31, 2019 at 5:04 AM Phong Tran <tranmanphong at gmail.com> wrote:
>
>> Sync the format with current state of kernel documentation.
>> This change base on rcu-dev branch
>> what changed:
>> - Format bullet lists
>> - Add literal blocks
>>
>> Signed-off-by: Phong Tran <tranmanphong at gmail.com>
>> ---
>>  Documentation/RCU/index.rst                   |   1 +
>>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>>  2 files changed, 90 insertions(+), 61 deletions(-)
>>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
>>
>> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
>> index 627128c230dc..b9b11481c727 100644
>> --- a/Documentation/RCU/index.rst
>> +++ b/Documentation/RCU/index.rst
>> @@ -8,6 +8,7 @@ RCU concepts
>>     :maxdepth: 3
>>
>>     arrayRCU
>> +   whatisRCU
>>     rcu
>>     listRCU
>>     NMI-RCU
>> diff --git a/Documentation/RCU/whatisRCU.txt
>> b/Documentation/RCU/whatisRCU.rst
>> similarity index 91%
>> rename from Documentation/RCU/whatisRCU.txt
>> rename to Documentation/RCU/whatisRCU.rst
>> index 58ba05c4d97f..70d0e4c21917 100644
>> --- a/Documentation/RCU/whatisRCU.txt
>> +++ b/Documentation/RCU/whatisRCU.rst
>> @@ -1,15 +1,18 @@
>> +.. _rcu_doc:
>> +
>>  What is RCU?  --  "Read, Copy, Update"
>> +======================================
>>
>>  Please note that the "What is RCU?" LWN series is an excellent place
>>  to start learning about RCU:
>>
>> -1.     What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
>> -2.     What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
>> -3.     RCU part 3: the RCU API      http://lwn.net/Articles/264090/
>> -4.     The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
>> -       2010 Big API Table           http://lwn.net/Articles/419086/
>> -5.     The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
>> -       2014 Big API Table           http://lwn.net/Articles/609973/
>> +| 1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
>> +| 2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
>> +| 3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
>> +| 4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
>> +|      2010 Big API Table           http://lwn.net/Articles/419086/
>> +| 5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
>> +|      2014 Big API Table           http://lwn.net/Articles/609973/
>>
>>
> Adding an external link here would be better.
> like this :  `text <link URL>`_
>
>  What is RCU?
>> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>>
>>
>>
> There is a list of topics that are covered in this documentation.
> Like this:
>
> 1. RCU OVERVIEW
> 2. WHAT IS RCU?S CORE API?
> 3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> 4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> ...
>
>  since this document is quite big adding cross-references to the above
> would be helpful.
>
>
>>  1.  RCU OVERVIEW
>> +----------------
>>
>>  The basic idea behind RCU is to split updates into "removal" and
>>  "reclamation" phases.  The removal phase removes references to data items
>> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>>
>>
>>  2.  WHAT IS RCU'S CORE API?
>> +---------------------------
>>
>>  The core RCU API is quite small:
>>
>> @@ -166,7 +171,7 @@ synchronize_rcu()
>>         read-side critical sections on all CPUs have completed.
>>         Note that synchronize_rcu() will -not- necessarily wait for
>>         any subsequent RCU read-side critical sections to complete.
>> -       For example, consider the following sequence of events:
>> +       For example, consider the following sequence of events::
>>
>>                  CPU 0                  CPU 1                 CPU 2
>>              ----------------- ------------------------- ---------------
>> @@ -248,13 +253,13 @@ rcu_dereference()
>>
>>         Common coding practice uses rcu_dereference() to copy an
>>         RCU-protected pointer to a local variable, then dereferences
>> -       this local variable, for example as follows:
>> +       this local variable, for example as follows::
>>
>>                 p = rcu_dereference(head.next);
>>                 return p->data;
>>
>>         However, in this case, one could just as easily combine these
>> -       into one statement:
>> +       into one statement::
>>
>>                 return rcu_dereference(head.next)->data;
>>
>> @@ -267,7 +272,7 @@ rcu_dereference()
>>
>>         Note that the value returned by rcu_dereference() is valid
>>         only within the enclosing RCU read-side critical section [1].
>> -       For example, the following is -not- legal:
>> +       For example, the following is -not- legal::
>>
>>                 rcu_read_lock();
>>                 p = rcu_dereference(head.next);
>> @@ -315,6 +320,7 @@ rcu_dereference()
>>
>>  The following diagram shows how each API communicates among the
>>  reader, updater, and reclaimer.
>> +::
>>
>>
>>             rcu_assign_pointer()
>> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>>
>>
>>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
>> +-----------------------------------------------
>>
>>  This section shows a simple use of the core RCU API to protect a
>>  global pointer to a dynamically allocated structure.  More-typical
>>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
>> +::
>>
>>         struct foo {
>>                 int a;
>> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>>
>>
>>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
>> +--------------------------------------------
>>
>>  In the example above, foo_update_a() blocks until a grace period elapses.
>>  This is quite simple, but in some cases one cannot afford to wait so
>>  long -- there might be other high-priority work to be done.
>>
>>  In such cases, one uses call_rcu() rather than synchronize_rcu().
>> -The call_rcu() API is as follows:
>> +The call_rcu() API is as follows::
>>
>>         void call_rcu(struct rcu_head * head,
>>                       void (*func)(struct rcu_head *head));
>> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>>  This function invokes func(head) after a grace period has elapsed.
>>  This invocation might happen from either softirq or process context,
>>  so the function is not permitted to block.  The foo struct needs to
>> -have an rcu_head structure added, perhaps as follows:
>> +have an rcu_head structure added, perhaps as follows::
>>
>>         struct foo {
>>                 int a;
>> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>>                 struct rcu_head rcu;
>>         };
>>
>> -The foo_update_a() function might then be written as follows:
>> +The foo_update_a() function might then be written as follows::
>>
>>         /*
>>          * Create a new struct foo that is the same as the one currently
>> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
>> follows:
>>                 call_rcu(&old_fp->rcu, foo_reclaim);
>>         }
>>
>> -The foo_reclaim() function might appear as follows:
>> +The foo_reclaim() function might appear as follows::
>>
>>         void foo_reclaim(struct rcu_head *rp)
>>         {
>> @@ -552,7 +561,7 @@ o   Use call_rcu() -after- removing a data element
>> from an
>>
>>  If the callback for call_rcu() is not doing anything more than calling
>>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
>> -to avoid having to write your own callback:
>> +to avoid having to write your own callback::
>>
>>         kfree_rcu(old_fp, rcu);
>>
>> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
>> governing the use of RCU.
>>
>>
>>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
>> +------------------------------------------------
>>
>>  One of the nice things about RCU is that it has extremely simple "toy"
>>  implementations that are a good first step towards understanding the
>> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
>> deadlock.
>>  However, it is probably the easiest implementation to relate to, so is
>>  a good starting point.
>>
>> -It is extremely simple:
>> +It is extremely simple::
>>
>>         static DEFINE_RWLOCK(rcu_gp_mutex);
>>
>> @@ -614,7 +624,7 @@ It is extremely simple:
>>
>>  [You can ignore rcu_assign_pointer() and rcu_dereference() without
>> missing
>>  much.  But here are simplified versions anyway.  And whatever you do,
>> -don't forget about them when submitting patches making use of RCU!]
>> +don't forget about them when submitting patches making use of RCU!]::
>>
>>         #define rcu_assign_pointer(p, v) \
>>         ({ \
>> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that
>> is based on
>>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>>  are the same as those shown in the preceding section, so they are
>> omitted.
>> +::
>>
>>         void rcu_read_lock(void) { }
>>
>> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU
>> read-side
>>
>>
>>  6.  ANALOGY WITH READER-WRITER LOCKING
>> +--------------------------------------
>>
>>  Although RCU can be used in many different ways, a very common use of
>>  RCU is analogous to reader-writer locking.  The following unified
>>  diff shows how closely related RCU and reader-writer locking can be.
>> +::
>>
>>         @@ -5,5 +5,5 @@ struct el {
>>                 int data;
>> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
>> locking can be.
>>                 return 0;
>>          }
>>
>> -Or, for those who prefer a side-by-side listing:
>> +Or, for those who prefer a side-by-side listing::
>>
>>   1 struct el {                          1 struct el {
>>   2   struct list_head list;             2   struct list_head list;
>> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>>   9 struct el head;                      9 struct el head;
>>
>> - 1 int search(long key, int *result)    1 int search(long key, int
>> *result)
>> - 2 {                                    2 {
>> - 3   struct list_head *lp;              3   struct list_head *lp;
>> - 4   struct el *p;                      4   struct el *p;
>> - 5                                      5
>> - 6   read_lock(&listmutex);             6   rcu_read_lock();
>> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
>> head, lp) {
>> - 8     if (p->key == key) {             8     if (p->key == key) {
>> - 9       *result = p->data;             9       *result = p->data;
>> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
>> -11       return 1;                     11       return 1;
>> -12     }                               12     }
>> -13   }                                 13   }
>> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
>> -15   return 0;                         15   return 0;
>> -16 }                                   16 }
>> -
>> - 1 int delete(long key)                 1 int delete(long key)
>> - 2 {                                    2 {
>> - 3   struct el *p;                      3   struct el *p;
>> - 4                                      4
>> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
>> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
>> lp) {
>> - 7     if (p->key == key) {             7     if (p->key == key) {
>> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
>> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
>> -                                       10       synchronize_rcu();
>> -10       kfree(p);                     11       kfree(p);
>> -11       return 1;                     12       return 1;
>> -12     }                               13     }
>> -13   }                                 14   }
>> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
>> -15   return 0;                         16   return 0;
>> -16 }                                   17 }
>> +::
>> +
>> +  1 int search(long key, int *result)    1 int search(long key, int
>> *result)
>> +  2 {                                    2 {
>> +  3   struct list_head *lp;              3   struct list_head *lp;
>> +  4   struct el *p;                      4   struct el *p;
>> +  5                                      5
>> +  6   read_lock(&listmutex);             6   rcu_read_lock();
>> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
>> head, lp) {
>> +  8     if (p->key == key) {             8     if (p->key == key) {
>> +  9       *result = p->data;             9       *result = p->data;
>> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
>> + 11       return 1;                     11       return 1;
>> + 12     }                               12     }
>> + 13   }                                 13   }
>> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
>> + 15   return 0;                         15   return 0;
>> + 16 }                                   16 }
>> +
>> +::
>> +
>> +  1 int delete(long key)                 1 int delete(long key)
>> +  2 {                                    2 {
>> +  3   struct el *p;                      3   struct el *p;
>> +  4                                      4
>> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
>> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
>> head, lp) {
>> +  7     if (p->key == key) {             7     if (p->key == key) {
>> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
>> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
>> +                                        10       synchronize_rcu();
>> + 10       kfree(p);                     11       kfree(p);
>> + 11       return 1;                     12       return 1;
>> + 12     }                               13     }
>> + 13   }                                 14   }
>> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
>> + 15   return 0;                         16   return 0;
>> + 16 }                                   17 }
>>
>>  Either way, the differences are quite small.  Read-side locking moves
>>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
>> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>>
>>
>>  7.  FULL LIST OF RCU APIs
>> +-------------------------
>>
>>  The RCU APIs are documented in docbook-format header comments in the
>>  Linux-kernel source code, but it helps to have a full list of the
>>  APIs, since there does not appear to be a way to categorize them
>>  in docbook.  Here is the list, by category.
>>
>> -RCU list traversal:
>> +RCU list traversal::
>>
>>         list_entry_rcu
>>         list_first_entry_rcu
>> @@ -854,7 +872,7 @@ RCU list traversal:
>>         hlist_bl_first_rcu
>>         hlist_bl_for_each_entry_rcu
>>
>> -RCU pointer/list update:
>> +RCU pointer/list udate::
>>
>>         rcu_assign_pointer
>>         list_add_rcu
>> @@ -876,7 +894,9 @@ RCU pointer/list update:
>>         hlist_bl_del_rcu
>>         hlist_bl_set_first_rcu
>>
>> -RCU:   Critical sections       Grace period            Barrier
>> +RCU::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock           synchronize_net         rcu_barrier
>>         rcu_read_unlock         synchronize_rcu
>> @@ -885,7 +905,9 @@ RCU:        Critical sections       Grace period
>>       Barrier
>>         rcu_dereference_check   kfree_rcu
>>         rcu_dereference_protected
>>
>> -bh:    Critical sections       Grace period            Barrier
>> +bh::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock_bh        call_rcu                rcu_barrier
>>         rcu_read_unlock_bh      synchronize_rcu
>> @@ -896,7 +918,9 @@ bh: Critical sections       Grace period
>> Barrier
>>         rcu_dereference_bh_protected
>>         rcu_read_lock_bh_held
>>
>> -sched: Critical sections       Grace period            Barrier
>> +sched::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock_sched     call_rcu                rcu_barrier
>>         rcu_read_unlock_sched   synchronize_rcu
>> @@ -910,7 +934,9 @@ sched:      Critical sections       Grace period
>>       Barrier
>>         rcu_read_lock_sched_held
>>
>>
>> -SRCU:  Critical sections       Grace period            Barrier
>> +SRCU::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         srcu_read_lock          call_srcu               srcu_barrier
>>         srcu_read_unlock        synchronize_srcu
>> @@ -918,13 +944,14 @@ SRCU:     Critical sections       Grace period
>>       Barrier
>>         srcu_dereference_check
>>         srcu_read_lock_held
>>
>> -SRCU:  Initialization/cleanup
>> +SRCU: Initialization/cleanup::
>> +
>>         DEFINE_SRCU
>>         DEFINE_STATIC_SRCU
>>         init_srcu_struct
>>         cleanup_srcu_struct
>>
>> -All:  lockdep-checked RCU-protected pointer access
>> +All: lockdep-checked RCU-protected pointer access::
>>
>>         rcu_access_pointer
>>         rcu_dereference_raw
>> @@ -976,6 +1003,7 @@ the right tool for your job.
>>
>>
>>  8.  ANSWERS TO QUICK QUIZZES
>> +----------------------------
>>
>>  Quick Quiz #1: Why is this argument naive?  How could a deadlock
>>                 occur when using this algorithm in a real-world Linux
>>
>
> Here, the formatting is not proper. In the rst file, the question should
> be added in the next line after Quick Quiz #1. Currently, half of the
> question appears in bold and the rest half does not.
> Also, as followed in all the documents there should be a cross-reference
> to the answer to this question. As this document is quite big having
> references would be helpful.
> The same applies to all other quick quiz questions in this document and in
> the Answers section as well the questions do not appear properly, half in
> bold text and half not bold.
>
> Apart from this, the other added changes look good!
>
> Thank you
> Madhuparna
>
> --
>> 2.20.1
>>
>> _______________________________________________
>> Linux-kernel-mentees mailing list
>> Linux-kernel-mentees at lists.linuxfoundation.org
>> https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
>>
> ?
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/attachments/20191102/27b15b9b/attachment-0001.html>

^ permalink raw reply	[flat|nested] 23+ messages in thread

* [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-02 12:00   ` tranmanphong at gmail.com (Phong Tran)
  2019-11-02 12:00     ` Phong Tran
@ 2019-11-02 12:00     ` tranmanphong
  1 sibling, 0 replies; 23+ messages in thread
From: tranmanphong @ 2019-11-02 12:00 UTC (permalink / raw)


On Sat, Nov 2, 2019 at 3:31 PM Madhuparna Bhowmik <
madhuparnabhowmik04 at gmail.com> wrote:

> I reviewed this patch, and I have the following suggestions:
>
> Thank for feedback. I did some change adding the cross-ref. patch sent
also apply in rcu-dev branch.

https://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/2019-November/001019.html

Regards,
Phong.

> On Thu, Oct 31, 2019 at 5:04 AM Phong Tran <tranmanphong at gmail.com> wrote:
>
>> Sync the format with current state of kernel documentation.
>> This change base on rcu-dev branch
>> what changed:
>> - Format bullet lists
>> - Add literal blocks
>>
>> Signed-off-by: Phong Tran <tranmanphong at gmail.com>
>> ---
>>  Documentation/RCU/index.rst                   |   1 +
>>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>>  2 files changed, 90 insertions(+), 61 deletions(-)
>>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
>>
>> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
>> index 627128c230dc..b9b11481c727 100644
>> --- a/Documentation/RCU/index.rst
>> +++ b/Documentation/RCU/index.rst
>> @@ -8,6 +8,7 @@ RCU concepts
>>     :maxdepth: 3
>>
>>     arrayRCU
>> +   whatisRCU
>>     rcu
>>     listRCU
>>     NMI-RCU
>> diff --git a/Documentation/RCU/whatisRCU.txt
>> b/Documentation/RCU/whatisRCU.rst
>> similarity index 91%
>> rename from Documentation/RCU/whatisRCU.txt
>> rename to Documentation/RCU/whatisRCU.rst
>> index 58ba05c4d97f..70d0e4c21917 100644
>> --- a/Documentation/RCU/whatisRCU.txt
>> +++ b/Documentation/RCU/whatisRCU.rst
>> @@ -1,15 +1,18 @@
>> +.. _rcu_doc:
>> +
>>  What is RCU?  --  "Read, Copy, Update"
>> +======================================
>>
>>  Please note that the "What is RCU?" LWN series is an excellent place
>>  to start learning about RCU:
>>
>> -1.     What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
>> -2.     What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
>> -3.     RCU part 3: the RCU API      http://lwn.net/Articles/264090/
>> -4.     The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
>> -       2010 Big API Table           http://lwn.net/Articles/419086/
>> -5.     The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
>> -       2014 Big API Table           http://lwn.net/Articles/609973/
>> +| 1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
>> +| 2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
>> +| 3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
>> +| 4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
>> +|      2010 Big API Table           http://lwn.net/Articles/419086/
>> +| 5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
>> +|      2014 Big API Table           http://lwn.net/Articles/609973/
>>
>>
> Adding an external link here would be better.
> like this :  `text <link URL>`_
>
>  What is RCU?
>> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>>
>>
>>
> There is a list of topics that are covered in this documentation.
> Like this:
>
> 1. RCU OVERVIEW
> 2. WHAT IS RCU?S CORE API?
> 3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> 4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> ...
>
>  since this document is quite big adding cross-references to the above
> would be helpful.
>
>
>>  1.  RCU OVERVIEW
>> +----------------
>>
>>  The basic idea behind RCU is to split updates into "removal" and
>>  "reclamation" phases.  The removal phase removes references to data items
>> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>>
>>
>>  2.  WHAT IS RCU'S CORE API?
>> +---------------------------
>>
>>  The core RCU API is quite small:
>>
>> @@ -166,7 +171,7 @@ synchronize_rcu()
>>         read-side critical sections on all CPUs have completed.
>>         Note that synchronize_rcu() will -not- necessarily wait for
>>         any subsequent RCU read-side critical sections to complete.
>> -       For example, consider the following sequence of events:
>> +       For example, consider the following sequence of events::
>>
>>                  CPU 0                  CPU 1                 CPU 2
>>              ----------------- ------------------------- ---------------
>> @@ -248,13 +253,13 @@ rcu_dereference()
>>
>>         Common coding practice uses rcu_dereference() to copy an
>>         RCU-protected pointer to a local variable, then dereferences
>> -       this local variable, for example as follows:
>> +       this local variable, for example as follows::
>>
>>                 p = rcu_dereference(head.next);
>>                 return p->data;
>>
>>         However, in this case, one could just as easily combine these
>> -       into one statement:
>> +       into one statement::
>>
>>                 return rcu_dereference(head.next)->data;
>>
>> @@ -267,7 +272,7 @@ rcu_dereference()
>>
>>         Note that the value returned by rcu_dereference() is valid
>>         only within the enclosing RCU read-side critical section [1].
>> -       For example, the following is -not- legal:
>> +       For example, the following is -not- legal::
>>
>>                 rcu_read_lock();
>>                 p = rcu_dereference(head.next);
>> @@ -315,6 +320,7 @@ rcu_dereference()
>>
>>  The following diagram shows how each API communicates among the
>>  reader, updater, and reclaimer.
>> +::
>>
>>
>>             rcu_assign_pointer()
>> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>>
>>
>>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
>> +-----------------------------------------------
>>
>>  This section shows a simple use of the core RCU API to protect a
>>  global pointer to a dynamically allocated structure.  More-typical
>>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
>> +::
>>
>>         struct foo {
>>                 int a;
>> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>>
>>
>>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
>> +--------------------------------------------
>>
>>  In the example above, foo_update_a() blocks until a grace period elapses.
>>  This is quite simple, but in some cases one cannot afford to wait so
>>  long -- there might be other high-priority work to be done.
>>
>>  In such cases, one uses call_rcu() rather than synchronize_rcu().
>> -The call_rcu() API is as follows:
>> +The call_rcu() API is as follows::
>>
>>         void call_rcu(struct rcu_head * head,
>>                       void (*func)(struct rcu_head *head));
>> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>>  This function invokes func(head) after a grace period has elapsed.
>>  This invocation might happen from either softirq or process context,
>>  so the function is not permitted to block.  The foo struct needs to
>> -have an rcu_head structure added, perhaps as follows:
>> +have an rcu_head structure added, perhaps as follows::
>>
>>         struct foo {
>>                 int a;
>> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>>                 struct rcu_head rcu;
>>         };
>>
>> -The foo_update_a() function might then be written as follows:
>> +The foo_update_a() function might then be written as follows::
>>
>>         /*
>>          * Create a new struct foo that is the same as the one currently
>> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
>> follows:
>>                 call_rcu(&old_fp->rcu, foo_reclaim);
>>         }
>>
>> -The foo_reclaim() function might appear as follows:
>> +The foo_reclaim() function might appear as follows::
>>
>>         void foo_reclaim(struct rcu_head *rp)
>>         {
>> @@ -552,7 +561,7 @@ o   Use call_rcu() -after- removing a data element
>> from an
>>
>>  If the callback for call_rcu() is not doing anything more than calling
>>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
>> -to avoid having to write your own callback:
>> +to avoid having to write your own callback::
>>
>>         kfree_rcu(old_fp, rcu);
>>
>> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
>> governing the use of RCU.
>>
>>
>>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
>> +------------------------------------------------
>>
>>  One of the nice things about RCU is that it has extremely simple "toy"
>>  implementations that are a good first step towards understanding the
>> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
>> deadlock.
>>  However, it is probably the easiest implementation to relate to, so is
>>  a good starting point.
>>
>> -It is extremely simple:
>> +It is extremely simple::
>>
>>         static DEFINE_RWLOCK(rcu_gp_mutex);
>>
>> @@ -614,7 +624,7 @@ It is extremely simple:
>>
>>  [You can ignore rcu_assign_pointer() and rcu_dereference() without
>> missing
>>  much.  But here are simplified versions anyway.  And whatever you do,
>> -don't forget about them when submitting patches making use of RCU!]
>> +don't forget about them when submitting patches making use of RCU!]::
>>
>>         #define rcu_assign_pointer(p, v) \
>>         ({ \
>> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that
>> is based on
>>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>>  are the same as those shown in the preceding section, so they are
>> omitted.
>> +::
>>
>>         void rcu_read_lock(void) { }
>>
>> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU
>> read-side
>>
>>
>>  6.  ANALOGY WITH READER-WRITER LOCKING
>> +--------------------------------------
>>
>>  Although RCU can be used in many different ways, a very common use of
>>  RCU is analogous to reader-writer locking.  The following unified
>>  diff shows how closely related RCU and reader-writer locking can be.
>> +::
>>
>>         @@ -5,5 +5,5 @@ struct el {
>>                 int data;
>> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
>> locking can be.
>>                 return 0;
>>          }
>>
>> -Or, for those who prefer a side-by-side listing:
>> +Or, for those who prefer a side-by-side listing::
>>
>>   1 struct el {                          1 struct el {
>>   2   struct list_head list;             2   struct list_head list;
>> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>>   9 struct el head;                      9 struct el head;
>>
>> - 1 int search(long key, int *result)    1 int search(long key, int
>> *result)
>> - 2 {                                    2 {
>> - 3   struct list_head *lp;              3   struct list_head *lp;
>> - 4   struct el *p;                      4   struct el *p;
>> - 5                                      5
>> - 6   read_lock(&listmutex);             6   rcu_read_lock();
>> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
>> head, lp) {
>> - 8     if (p->key == key) {             8     if (p->key == key) {
>> - 9       *result = p->data;             9       *result = p->data;
>> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
>> -11       return 1;                     11       return 1;
>> -12     }                               12     }
>> -13   }                                 13   }
>> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
>> -15   return 0;                         15   return 0;
>> -16 }                                   16 }
>> -
>> - 1 int delete(long key)                 1 int delete(long key)
>> - 2 {                                    2 {
>> - 3   struct el *p;                      3   struct el *p;
>> - 4                                      4
>> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
>> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
>> lp) {
>> - 7     if (p->key == key) {             7     if (p->key == key) {
>> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
>> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
>> -                                       10       synchronize_rcu();
>> -10       kfree(p);                     11       kfree(p);
>> -11       return 1;                     12       return 1;
>> -12     }                               13     }
>> -13   }                                 14   }
>> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
>> -15   return 0;                         16   return 0;
>> -16 }                                   17 }
>> +::
>> +
>> +  1 int search(long key, int *result)    1 int search(long key, int
>> *result)
>> +  2 {                                    2 {
>> +  3   struct list_head *lp;              3   struct list_head *lp;
>> +  4   struct el *p;                      4   struct el *p;
>> +  5                                      5
>> +  6   read_lock(&listmutex);             6   rcu_read_lock();
>> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
>> head, lp) {
>> +  8     if (p->key == key) {             8     if (p->key == key) {
>> +  9       *result = p->data;             9       *result = p->data;
>> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
>> + 11       return 1;                     11       return 1;
>> + 12     }                               12     }
>> + 13   }                                 13   }
>> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
>> + 15   return 0;                         15   return 0;
>> + 16 }                                   16 }
>> +
>> +::
>> +
>> +  1 int delete(long key)                 1 int delete(long key)
>> +  2 {                                    2 {
>> +  3   struct el *p;                      3   struct el *p;
>> +  4                                      4
>> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
>> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
>> head, lp) {
>> +  7     if (p->key == key) {             7     if (p->key == key) {
>> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
>> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
>> +                                        10       synchronize_rcu();
>> + 10       kfree(p);                     11       kfree(p);
>> + 11       return 1;                     12       return 1;
>> + 12     }                               13     }
>> + 13   }                                 14   }
>> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
>> + 15   return 0;                         16   return 0;
>> + 16 }                                   17 }
>>
>>  Either way, the differences are quite small.  Read-side locking moves
>>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
>> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>>
>>
>>  7.  FULL LIST OF RCU APIs
>> +-------------------------
>>
>>  The RCU APIs are documented in docbook-format header comments in the
>>  Linux-kernel source code, but it helps to have a full list of the
>>  APIs, since there does not appear to be a way to categorize them
>>  in docbook.  Here is the list, by category.
>>
>> -RCU list traversal:
>> +RCU list traversal::
>>
>>         list_entry_rcu
>>         list_first_entry_rcu
>> @@ -854,7 +872,7 @@ RCU list traversal:
>>         hlist_bl_first_rcu
>>         hlist_bl_for_each_entry_rcu
>>
>> -RCU pointer/list update:
>> +RCU pointer/list udate::
>>
>>         rcu_assign_pointer
>>         list_add_rcu
>> @@ -876,7 +894,9 @@ RCU pointer/list update:
>>         hlist_bl_del_rcu
>>         hlist_bl_set_first_rcu
>>
>> -RCU:   Critical sections       Grace period            Barrier
>> +RCU::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock           synchronize_net         rcu_barrier
>>         rcu_read_unlock         synchronize_rcu
>> @@ -885,7 +905,9 @@ RCU:        Critical sections       Grace period
>>       Barrier
>>         rcu_dereference_check   kfree_rcu
>>         rcu_dereference_protected
>>
>> -bh:    Critical sections       Grace period            Barrier
>> +bh::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock_bh        call_rcu                rcu_barrier
>>         rcu_read_unlock_bh      synchronize_rcu
>> @@ -896,7 +918,9 @@ bh: Critical sections       Grace period
>> Barrier
>>         rcu_dereference_bh_protected
>>         rcu_read_lock_bh_held
>>
>> -sched: Critical sections       Grace period            Barrier
>> +sched::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock_sched     call_rcu                rcu_barrier
>>         rcu_read_unlock_sched   synchronize_rcu
>> @@ -910,7 +934,9 @@ sched:      Critical sections       Grace period
>>       Barrier
>>         rcu_read_lock_sched_held
>>
>>
>> -SRCU:  Critical sections       Grace period            Barrier
>> +SRCU::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         srcu_read_lock          call_srcu               srcu_barrier
>>         srcu_read_unlock        synchronize_srcu
>> @@ -918,13 +944,14 @@ SRCU:     Critical sections       Grace period
>>       Barrier
>>         srcu_dereference_check
>>         srcu_read_lock_held
>>
>> -SRCU:  Initialization/cleanup
>> +SRCU: Initialization/cleanup::
>> +
>>         DEFINE_SRCU
>>         DEFINE_STATIC_SRCU
>>         init_srcu_struct
>>         cleanup_srcu_struct
>>
>> -All:  lockdep-checked RCU-protected pointer access
>> +All: lockdep-checked RCU-protected pointer access::
>>
>>         rcu_access_pointer
>>         rcu_dereference_raw
>> @@ -976,6 +1003,7 @@ the right tool for your job.
>>
>>
>>  8.  ANSWERS TO QUICK QUIZZES
>> +----------------------------
>>
>>  Quick Quiz #1: Why is this argument naive?  How could a deadlock
>>                 occur when using this algorithm in a real-world Linux
>>
>
> Here, the formatting is not proper. In the rst file, the question should
> be added in the next line after Quick Quiz #1. Currently, half of the
> question appears in bold and the rest half does not.
> Also, as followed in all the documents there should be a cross-reference
> to the answer to this question. As this document is quite big having
> references would be helpful.
> The same applies to all other quick quiz questions in this document and in
> the Answers section as well the questions do not appear properly, half in
> bold text and half not bold.
>
> Apart from this, the other added changes look good!
>
> Thank you
> Madhuparna
>
> --
>> 2.20.1
>>
>> _______________________________________________
>> Linux-kernel-mentees mailing list
>> Linux-kernel-mentees at lists.linuxfoundation.org
>> https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
>>
> ?
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/attachments/20191102/27b15b9b/attachment-0001.html>

^ permalink raw reply	[flat|nested] 23+ messages in thread

* Re: [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst
  2019-11-02 12:00   ` tranmanphong at gmail.com (Phong Tran)
@ 2019-11-02 12:00     ` Phong Tran
  2019-11-02 12:00     ` tranmanphong
  1 sibling, 0 replies; 23+ messages in thread
From: Phong Tran @ 2019-11-02 12:00 UTC (permalink / raw)
  To: Madhuparna Bhowmik
  Cc: paulmck, Jonathan Corbet, linux-doc, jiangshanlai, josh, rostedt,
	linux-kernel, rcu, mathieu.desnoyers, Joel Fernandes,
	linux-kernel-mentees

[-- Attachment #1.1: Type: text/plain, Size: 19569 bytes --]

On Sat, Nov 2, 2019 at 3:31 PM Madhuparna Bhowmik <
madhuparnabhowmik04@gmail.com> wrote:

> I reviewed this patch, and I have the following suggestions:
>
> Thank for feedback. I did some change adding the cross-ref. patch sent
also apply in rcu-dev branch.

https://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/2019-November/001019.html

Regards,
Phong.

> On Thu, Oct 31, 2019 at 5:04 AM Phong Tran <tranmanphong@gmail.com> wrote:
>
>> Sync the format with current state of kernel documentation.
>> This change base on rcu-dev branch
>> what changed:
>> - Format bullet lists
>> - Add literal blocks
>>
>> Signed-off-by: Phong Tran <tranmanphong@gmail.com>
>> ---
>>  Documentation/RCU/index.rst                   |   1 +
>>  .../RCU/{whatisRCU.txt => whatisRCU.rst}      | 150 +++++++++++-------
>>  2 files changed, 90 insertions(+), 61 deletions(-)
>>  rename Documentation/RCU/{whatisRCU.txt => whatisRCU.rst} (91%)
>>
>> diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst
>> index 627128c230dc..b9b11481c727 100644
>> --- a/Documentation/RCU/index.rst
>> +++ b/Documentation/RCU/index.rst
>> @@ -8,6 +8,7 @@ RCU concepts
>>     :maxdepth: 3
>>
>>     arrayRCU
>> +   whatisRCU
>>     rcu
>>     listRCU
>>     NMI-RCU
>> diff --git a/Documentation/RCU/whatisRCU.txt
>> b/Documentation/RCU/whatisRCU.rst
>> similarity index 91%
>> rename from Documentation/RCU/whatisRCU.txt
>> rename to Documentation/RCU/whatisRCU.rst
>> index 58ba05c4d97f..70d0e4c21917 100644
>> --- a/Documentation/RCU/whatisRCU.txt
>> +++ b/Documentation/RCU/whatisRCU.rst
>> @@ -1,15 +1,18 @@
>> +.. _rcu_doc:
>> +
>>  What is RCU?  --  "Read, Copy, Update"
>> +======================================
>>
>>  Please note that the "What is RCU?" LWN series is an excellent place
>>  to start learning about RCU:
>>
>> -1.     What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
>> -2.     What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
>> -3.     RCU part 3: the RCU API      http://lwn.net/Articles/264090/
>> -4.     The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
>> -       2010 Big API Table           http://lwn.net/Articles/419086/
>> -5.     The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
>> -       2014 Big API Table           http://lwn.net/Articles/609973/
>> +| 1.   What is RCU, Fundamentally?  http://lwn.net/Articles/262464/
>> +| 2.   What is RCU? Part 2: Usage   http://lwn.net/Articles/263130/
>> +| 3.   RCU part 3: the RCU API      http://lwn.net/Articles/264090/
>> +| 4.   The RCU API, 2010 Edition    http://lwn.net/Articles/418853/
>> +|      2010 Big API Table           http://lwn.net/Articles/419086/
>> +| 5.   The RCU API, 2014 Edition    http://lwn.net/Articles/609904/
>> +|      2014 Big API Table           http://lwn.net/Articles/609973/
>>
>>
> Adding an external link here would be better.
> like this :  `text <link URL>`_
>
>  What is RCU?
>> @@ -51,6 +54,7 @@ never need this document anyway.  ;-)
>>
>>
>>
> There is a list of topics that are covered in this documentation.
> Like this:
>
> 1. RCU OVERVIEW
> 2. WHAT IS RCU’S CORE API?
> 3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
> 4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?
> ...
>
>  since this document is quite big adding cross-references to the above
> would be helpful.
>
>
>>  1.  RCU OVERVIEW
>> +----------------
>>
>>  The basic idea behind RCU is to split updates into "removal" and
>>  "reclamation" phases.  The removal phase removes references to data items
>> @@ -118,6 +122,7 @@ Read on to learn about how RCU's API makes this easy.
>>
>>
>>  2.  WHAT IS RCU'S CORE API?
>> +---------------------------
>>
>>  The core RCU API is quite small:
>>
>> @@ -166,7 +171,7 @@ synchronize_rcu()
>>         read-side critical sections on all CPUs have completed.
>>         Note that synchronize_rcu() will -not- necessarily wait for
>>         any subsequent RCU read-side critical sections to complete.
>> -       For example, consider the following sequence of events:
>> +       For example, consider the following sequence of events::
>>
>>                  CPU 0                  CPU 1                 CPU 2
>>              ----------------- ------------------------- ---------------
>> @@ -248,13 +253,13 @@ rcu_dereference()
>>
>>         Common coding practice uses rcu_dereference() to copy an
>>         RCU-protected pointer to a local variable, then dereferences
>> -       this local variable, for example as follows:
>> +       this local variable, for example as follows::
>>
>>                 p = rcu_dereference(head.next);
>>                 return p->data;
>>
>>         However, in this case, one could just as easily combine these
>> -       into one statement:
>> +       into one statement::
>>
>>                 return rcu_dereference(head.next)->data;
>>
>> @@ -267,7 +272,7 @@ rcu_dereference()
>>
>>         Note that the value returned by rcu_dereference() is valid
>>         only within the enclosing RCU read-side critical section [1].
>> -       For example, the following is -not- legal:
>> +       For example, the following is -not- legal::
>>
>>                 rcu_read_lock();
>>                 p = rcu_dereference(head.next);
>> @@ -315,6 +320,7 @@ rcu_dereference()
>>
>>  The following diagram shows how each API communicates among the
>>  reader, updater, and reclaimer.
>> +::
>>
>>
>>             rcu_assign_pointer()
>> @@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.
>>
>>
>>  3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?
>> +-----------------------------------------------
>>
>>  This section shows a simple use of the core RCU API to protect a
>>  global pointer to a dynamically allocated structure.  More-typical
>>  uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
>> +::
>>
>>         struct foo {
>>                 int a;
>> @@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.
>>
>>
>>  4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?
>> +--------------------------------------------
>>
>>  In the example above, foo_update_a() blocks until a grace period elapses.
>>  This is quite simple, but in some cases one cannot afford to wait so
>>  long -- there might be other high-priority work to be done.
>>
>>  In such cases, one uses call_rcu() rather than synchronize_rcu().
>> -The call_rcu() API is as follows:
>> +The call_rcu() API is as follows::
>>
>>         void call_rcu(struct rcu_head * head,
>>                       void (*func)(struct rcu_head *head));
>> @@ -481,7 +490,7 @@ The call_rcu() API is as follows:
>>  This function invokes func(head) after a grace period has elapsed.
>>  This invocation might happen from either softirq or process context,
>>  so the function is not permitted to block.  The foo struct needs to
>> -have an rcu_head structure added, perhaps as follows:
>> +have an rcu_head structure added, perhaps as follows::
>>
>>         struct foo {
>>                 int a;
>> @@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:
>>                 struct rcu_head rcu;
>>         };
>>
>> -The foo_update_a() function might then be written as follows:
>> +The foo_update_a() function might then be written as follows::
>>
>>         /*
>>          * Create a new struct foo that is the same as the one currently
>> @@ -520,7 +529,7 @@ The foo_update_a() function might then be written as
>> follows:
>>                 call_rcu(&old_fp->rcu, foo_reclaim);
>>         }
>>
>> -The foo_reclaim() function might appear as follows:
>> +The foo_reclaim() function might appear as follows::
>>
>>         void foo_reclaim(struct rcu_head *rp)
>>         {
>> @@ -552,7 +561,7 @@ o   Use call_rcu() -after- removing a data element
>> from an
>>
>>  If the callback for call_rcu() is not doing anything more than calling
>>  kfree() on the structure, you can use kfree_rcu() instead of call_rcu()
>> -to avoid having to write your own callback:
>> +to avoid having to write your own callback::
>>
>>         kfree_rcu(old_fp, rcu);
>>
>> @@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules
>> governing the use of RCU.
>>
>>
>>  5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?
>> +------------------------------------------------
>>
>>  One of the nice things about RCU is that it has extremely simple "toy"
>>  implementations that are a good first step towards understanding the
>> @@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can
>> deadlock.
>>  However, it is probably the easiest implementation to relate to, so is
>>  a good starting point.
>>
>> -It is extremely simple:
>> +It is extremely simple::
>>
>>         static DEFINE_RWLOCK(rcu_gp_mutex);
>>
>> @@ -614,7 +624,7 @@ It is extremely simple:
>>
>>  [You can ignore rcu_assign_pointer() and rcu_dereference() without
>> missing
>>  much.  But here are simplified versions anyway.  And whatever you do,
>> -don't forget about them when submitting patches making use of RCU!]
>> +don't forget about them when submitting patches making use of RCU!]::
>>
>>         #define rcu_assign_pointer(p, v) \
>>         ({ \
>> @@ -659,6 +669,7 @@ This section presents a "toy" RCU implementation that
>> is based on
>>  on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT
>>  kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()
>>  are the same as those shown in the preceding section, so they are
>> omitted.
>> +::
>>
>>         void rcu_read_lock(void) { }
>>
>> @@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU
>> read-side
>>
>>
>>  6.  ANALOGY WITH READER-WRITER LOCKING
>> +--------------------------------------
>>
>>  Although RCU can be used in many different ways, a very common use of
>>  RCU is analogous to reader-writer locking.  The following unified
>>  diff shows how closely related RCU and reader-writer locking can be.
>> +::
>>
>>         @@ -5,5 +5,5 @@ struct el {
>>                 int data;
>> @@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer
>> locking can be.
>>                 return 0;
>>          }
>>
>> -Or, for those who prefer a side-by-side listing:
>> +Or, for those who prefer a side-by-side listing::
>>
>>   1 struct el {                          1 struct el {
>>   2   struct list_head list;             2   struct list_head list;
>> @@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:
>>   8 rwlock_t listmutex;                  8 spinlock_t listmutex;
>>   9 struct el head;                      9 struct el head;
>>
>> - 1 int search(long key, int *result)    1 int search(long key, int
>> *result)
>> - 2 {                                    2 {
>> - 3   struct list_head *lp;              3   struct list_head *lp;
>> - 4   struct el *p;                      4   struct el *p;
>> - 5                                      5
>> - 6   read_lock(&listmutex);             6   rcu_read_lock();
>> - 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
>> head, lp) {
>> - 8     if (p->key == key) {             8     if (p->key == key) {
>> - 9       *result = p->data;             9       *result = p->data;
>> -10       read_unlock(&listmutex);      10       rcu_read_unlock();
>> -11       return 1;                     11       return 1;
>> -12     }                               12     }
>> -13   }                                 13   }
>> -14   read_unlock(&listmutex);          14   rcu_read_unlock();
>> -15   return 0;                         15   return 0;
>> -16 }                                   16 }
>> -
>> - 1 int delete(long key)                 1 int delete(long key)
>> - 2 {                                    2 {
>> - 3   struct el *p;                      3   struct el *p;
>> - 4                                      4
>> - 5   write_lock(&listmutex);            5   spin_lock(&listmutex);
>> - 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head,
>> lp) {
>> - 7     if (p->key == key) {             7     if (p->key == key) {
>> - 8       list_del(&p->list);            8       list_del_rcu(&p->list);
>> - 9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
>> -                                       10       synchronize_rcu();
>> -10       kfree(p);                     11       kfree(p);
>> -11       return 1;                     12       return 1;
>> -12     }                               13     }
>> -13   }                                 14   }
>> -14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
>> -15   return 0;                         16   return 0;
>> -16 }                                   17 }
>> +::
>> +
>> +  1 int search(long key, int *result)    1 int search(long key, int
>> *result)
>> +  2 {                                    2 {
>> +  3   struct list_head *lp;              3   struct list_head *lp;
>> +  4   struct el *p;                      4   struct el *p;
>> +  5                                      5
>> +  6   read_lock(&listmutex);             6   rcu_read_lock();
>> +  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p,
>> head, lp) {
>> +  8     if (p->key == key) {             8     if (p->key == key) {
>> +  9       *result = p->data;             9       *result = p->data;
>> + 10       read_unlock(&listmutex);      10       rcu_read_unlock();
>> + 11       return 1;                     11       return 1;
>> + 12     }                               12     }
>> + 13   }                                 13   }
>> + 14   read_unlock(&listmutex);          14   rcu_read_unlock();
>> + 15   return 0;                         15   return 0;
>> + 16 }                                   16 }
>> +
>> +::
>> +
>> +  1 int delete(long key)                 1 int delete(long key)
>> +  2 {                                    2 {
>> +  3   struct el *p;                      3   struct el *p;
>> +  4                                      4
>> +  5   write_lock(&listmutex);            5   spin_lock(&listmutex);
>> +  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p,
>> head, lp) {
>> +  7     if (p->key == key) {             7     if (p->key == key) {
>> +  8       list_del(&p->list);            8       list_del_rcu(&p->list);
>> +  9       write_unlock(&listmutex);      9       spin_unlock(&listmutex);
>> +                                        10       synchronize_rcu();
>> + 10       kfree(p);                     11       kfree(p);
>> + 11       return 1;                     12       return 1;
>> + 12     }                               13     }
>> + 13   }                                 14   }
>> + 14   write_unlock(&listmutex);         15   spin_unlock(&listmutex);
>> + 15   return 0;                         16   return 0;
>> + 16 }                                   17 }
>>
>>  Either way, the differences are quite small.  Read-side locking moves
>>  to rcu_read_lock() and rcu_read_unlock, update-side locking moves from
>> @@ -827,13 +844,14 @@ be used in place of synchronize_rcu().
>>
>>
>>  7.  FULL LIST OF RCU APIs
>> +-------------------------
>>
>>  The RCU APIs are documented in docbook-format header comments in the
>>  Linux-kernel source code, but it helps to have a full list of the
>>  APIs, since there does not appear to be a way to categorize them
>>  in docbook.  Here is the list, by category.
>>
>> -RCU list traversal:
>> +RCU list traversal::
>>
>>         list_entry_rcu
>>         list_first_entry_rcu
>> @@ -854,7 +872,7 @@ RCU list traversal:
>>         hlist_bl_first_rcu
>>         hlist_bl_for_each_entry_rcu
>>
>> -RCU pointer/list update:
>> +RCU pointer/list udate::
>>
>>         rcu_assign_pointer
>>         list_add_rcu
>> @@ -876,7 +894,9 @@ RCU pointer/list update:
>>         hlist_bl_del_rcu
>>         hlist_bl_set_first_rcu
>>
>> -RCU:   Critical sections       Grace period            Barrier
>> +RCU::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock           synchronize_net         rcu_barrier
>>         rcu_read_unlock         synchronize_rcu
>> @@ -885,7 +905,9 @@ RCU:        Critical sections       Grace period
>>       Barrier
>>         rcu_dereference_check   kfree_rcu
>>         rcu_dereference_protected
>>
>> -bh:    Critical sections       Grace period            Barrier
>> +bh::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock_bh        call_rcu                rcu_barrier
>>         rcu_read_unlock_bh      synchronize_rcu
>> @@ -896,7 +918,9 @@ bh: Critical sections       Grace period
>> Barrier
>>         rcu_dereference_bh_protected
>>         rcu_read_lock_bh_held
>>
>> -sched: Critical sections       Grace period            Barrier
>> +sched::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         rcu_read_lock_sched     call_rcu                rcu_barrier
>>         rcu_read_unlock_sched   synchronize_rcu
>> @@ -910,7 +934,9 @@ sched:      Critical sections       Grace period
>>       Barrier
>>         rcu_read_lock_sched_held
>>
>>
>> -SRCU:  Critical sections       Grace period            Barrier
>> +SRCU::
>> +
>> +       Critical sections       Grace period            Barrier
>>
>>         srcu_read_lock          call_srcu               srcu_barrier
>>         srcu_read_unlock        synchronize_srcu
>> @@ -918,13 +944,14 @@ SRCU:     Critical sections       Grace period
>>       Barrier
>>         srcu_dereference_check
>>         srcu_read_lock_held
>>
>> -SRCU:  Initialization/cleanup
>> +SRCU: Initialization/cleanup::
>> +
>>         DEFINE_SRCU
>>         DEFINE_STATIC_SRCU
>>         init_srcu_struct
>>         cleanup_srcu_struct
>>
>> -All:  lockdep-checked RCU-protected pointer access
>> +All: lockdep-checked RCU-protected pointer access::
>>
>>         rcu_access_pointer
>>         rcu_dereference_raw
>> @@ -976,6 +1003,7 @@ the right tool for your job.
>>
>>
>>  8.  ANSWERS TO QUICK QUIZZES
>> +----------------------------
>>
>>  Quick Quiz #1: Why is this argument naive?  How could a deadlock
>>                 occur when using this algorithm in a real-world Linux
>>
>
> Here, the formatting is not proper. In the rst file, the question should
> be added in the next line after Quick Quiz #1. Currently, half of the
> question appears in bold and the rest half does not.
> Also, as followed in all the documents there should be a cross-reference
> to the answer to this question. As this document is quite big having
> references would be helpful.
> The same applies to all other quick quiz questions in this document and in
> the Answers section as well the questions do not appear properly, half in
> bold text and half not bold.
>
> Apart from this, the other added changes look good!
>
> Thank you
> Madhuparna
>
> --
>> 2.20.1
>>
>> _______________________________________________
>> Linux-kernel-mentees mailing list
>> Linux-kernel-mentees@lists.linuxfoundation.org
>> https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
>>
> ᐧ
>

[-- Attachment #1.2: Type: text/html, Size: 25720 bytes --]

<div dir="ltr"><div dir="ltr">On Sat, Nov 2, 2019 at 3:31 PM Madhuparna Bhowmik &lt;<a href="mailto:madhuparnabhowmik04@gmail.com">madhuparnabhowmik04@gmail.com</a>&gt; wrote:<br></div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>I reviewed this patch, and I have the following suggestions:</div><br></div></blockquote><div>Thank for feedback. I did some change adding the cross-ref. patch sent</div><div>also apply in rcu-dev branch.</div><div><br></div><div><a href="https://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/2019-November/001019.html">https://lists.linuxfoundation.org/pipermail/linux-kernel-mentees/2019-November/001019.html</a></div><div><br></div><div>Regards,</div><div>Phong. <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Oct 31, 2019 at 5:04 AM Phong Tran &lt;<a href="mailto:tranmanphong@gmail.com" target="_blank">tranmanphong@gmail.com</a>&gt; wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Sync the format with current state of kernel documentation.<br>
This change base on rcu-dev branch<br>
what changed:<br>
- Format bullet lists<br>
- Add literal blocks<br>
<br>
Signed-off-by: Phong Tran &lt;<a href="mailto:tranmanphong@gmail.com" target="_blank">tranmanphong@gmail.com</a>&gt;<br>
---<br>
 Documentation/RCU/index.rst                   |   1 +<br>
 .../RCU/{whatisRCU.txt =&gt; whatisRCU.rst}      | 150 +++++++++++-------<br>
 2 files changed, 90 insertions(+), 61 deletions(-)<br>
 rename Documentation/RCU/{whatisRCU.txt =&gt; whatisRCU.rst} (91%)<br>
<br>
diff --git a/Documentation/RCU/index.rst b/Documentation/RCU/index.rst<br>
index 627128c230dc..b9b11481c727 100644<br>
--- a/Documentation/RCU/index.rst<br>
+++ b/Documentation/RCU/index.rst<br>
@@ -8,6 +8,7 @@ RCU concepts<br>
    :maxdepth: 3<br>
<br>
    arrayRCU<br>
+   whatisRCU<br>
    rcu<br>
    listRCU<br>
    NMI-RCU<br>
diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.rst<br>
similarity index 91%<br>
rename from Documentation/RCU/whatisRCU.txt<br>
rename to Documentation/RCU/whatisRCU.rst<br>
index 58ba05c4d97f..70d0e4c21917 100644<br>
--- a/Documentation/RCU/whatisRCU.txt<br>
+++ b/Documentation/RCU/whatisRCU.rst<br>
@@ -1,15 +1,18 @@<br>
+.. _rcu_doc:<br>
+<br>
 What is RCU?  --  &quot;Read, Copy, Update&quot;<br>
+======================================<br>
<br>
 Please note that the &quot;What is RCU?&quot; LWN series is an excellent place<br>
 to start learning about RCU:<br>
<br>
-1.     What is RCU, Fundamentally?  <a href="http://lwn.net/Articles/262464/" rel="noreferrer" target="_blank">http://lwn.net/Articles/262464/</a><br>
-2.     What is RCU? Part 2: Usage   <a href="http://lwn.net/Articles/263130/" rel="noreferrer" target="_blank">http://lwn.net/Articles/263130/</a><br>
-3.     RCU part 3: the RCU API      <a href="http://lwn.net/Articles/264090/" rel="noreferrer" target="_blank">http://lwn.net/Articles/264090/</a><br>
-4.     The RCU API, 2010 Edition    <a href="http://lwn.net/Articles/418853/" rel="noreferrer" target="_blank">http://lwn.net/Articles/418853/</a><br>
-       2010 Big API Table           <a href="http://lwn.net/Articles/419086/" rel="noreferrer" target="_blank">http://lwn.net/Articles/419086/</a><br>
-5.     The RCU API, 2014 Edition    <a href="http://lwn.net/Articles/609904/" rel="noreferrer" target="_blank">http://lwn.net/Articles/609904/</a><br>
-       2014 Big API Table           <a href="http://lwn.net/Articles/609973/" rel="noreferrer" target="_blank">http://lwn.net/Articles/609973/</a><br>
+| 1.   What is RCU, Fundamentally?  <a href="http://lwn.net/Articles/262464/" rel="noreferrer" target="_blank">http://lwn.net/Articles/262464/</a><br>
+| 2.   What is RCU? Part 2: Usage   <a href="http://lwn.net/Articles/263130/" rel="noreferrer" target="_blank">http://lwn.net/Articles/263130/</a><br>
+| 3.   RCU part 3: the RCU API      <a href="http://lwn.net/Articles/264090/" rel="noreferrer" target="_blank">http://lwn.net/Articles/264090/</a><br>
+| 4.   The RCU API, 2010 Edition    <a href="http://lwn.net/Articles/418853/" rel="noreferrer" target="_blank">http://lwn.net/Articles/418853/</a><br>
+|      2010 Big API Table           <a href="http://lwn.net/Articles/419086/" rel="noreferrer" target="_blank">http://lwn.net/Articles/419086/</a><br>
+| 5.   The RCU API, 2014 Edition    <a href="http://lwn.net/Articles/609904/" rel="noreferrer" target="_blank">http://lwn.net/Articles/609904/</a><br>
+|      2014 Big API Table           <a href="http://lwn.net/Articles/609973/" rel="noreferrer" target="_blank">http://lwn.net/Articles/609973/</a><br><br></blockquote><div><br></div><div>Adding an external link here would be better.</div><div>like this :  <span style="font-family:Menlo,Monaco,Consolas,&quot;Courier New&quot;,monospace;font-size:13px;box-sizing:border-box;color:rgb(64,112,160)">`text </span><span style="font-family:Menlo,Monaco,Consolas,&quot;Courier New&quot;,monospace;font-size:13px;box-sizing:border-box;color:rgb(112,160,208);font-style:italic">&lt;link URL&gt;</span><span style="font-family:Menlo,Monaco,Consolas,&quot;Courier New&quot;,monospace;font-size:13px;box-sizing:border-box;color:rgb(64,112,160)">`_</span> </div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
 What is RCU?<br>
@@ -51,6 +54,7 @@ never need this document anyway.  ;-)<br>
<br>
<br></blockquote><div><br></div><div>There is a list of topics that are covered in this documentation.</div><div>Like this:</div><div><br></div><div>1. RCU OVERVIEW<br>2. WHAT IS RCU’S CORE API?<br>3. WHAT ARE SOME EXAMPLE USES OF CORE RCU API?<br>4. WHAT IF MY UPDATING THREAD CANNOT BLOCK?<br></div><div>...</div><div><br></div><div> since this document is quite big adding cross-references to the above would be helpful.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
 1.  RCU OVERVIEW<br>
+----------------<br>
<br>
 The basic idea behind RCU is to split updates into &quot;removal&quot; and<br>
 &quot;reclamation&quot; phases.  The removal phase removes references to data items<br>
@@ -118,6 +122,7 @@ Read on to learn about how RCU&#39;s API makes this easy.<br>
<br>
<br>
 2.  WHAT IS RCU&#39;S CORE API?<br>
+---------------------------<br>
<br>
 The core RCU API is quite small:<br>
<br>
@@ -166,7 +171,7 @@ synchronize_rcu()<br>
        read-side critical sections on all CPUs have completed.<br>
        Note that synchronize_rcu() will -not- necessarily wait for<br>
        any subsequent RCU read-side critical sections to complete.<br>
-       For example, consider the following sequence of events:<br>
+       For example, consider the following sequence of events::<br>
<br>
                 CPU 0                  CPU 1                 CPU 2<br>
             ----------------- ------------------------- ---------------<br>
@@ -248,13 +253,13 @@ rcu_dereference()<br>
<br>
        Common coding practice uses rcu_dereference() to copy an<br>
        RCU-protected pointer to a local variable, then dereferences<br>
-       this local variable, for example as follows:<br>
+       this local variable, for example as follows::<br>
<br>
                p = rcu_dereference(head.next);<br>
                return p-&gt;data;<br>
<br>
        However, in this case, one could just as easily combine these<br>
-       into one statement:<br>
+       into one statement::<br>
<br>
                return rcu_dereference(head.next)-&gt;data;<br>
<br>
@@ -267,7 +272,7 @@ rcu_dereference()<br>
<br>
        Note that the value returned by rcu_dereference() is valid<br>
        only within the enclosing RCU read-side critical section [1].<br>
-       For example, the following is -not- legal:<br>
+       For example, the following is -not- legal::<br>
<br>
                rcu_read_lock();<br>
                p = rcu_dereference(head.next);<br>
@@ -315,6 +320,7 @@ rcu_dereference()<br>
<br>
 The following diagram shows how each API communicates among the<br>
 reader, updater, and reclaimer.<br>
+::<br>
<br>
<br>
            rcu_assign_pointer()<br>
@@ -377,10 +383,12 @@ for specialized uses, but are relatively uncommon.<br>
<br>
<br>
 3.  WHAT ARE SOME EXAMPLE USES OF CORE RCU API?<br>
+-----------------------------------------------<br>
<br>
 This section shows a simple use of the core RCU API to protect a<br>
 global pointer to a dynamically allocated structure.  More-typical<br>
 uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.<br>
+::<br>
<br>
        struct foo {<br>
                int a;<br>
@@ -467,13 +475,14 @@ arrayRCU.txt, and NMI-RCU.txt.<br>
<br>
<br>
 4.  WHAT IF MY UPDATING THREAD CANNOT BLOCK?<br>
+--------------------------------------------<br>
<br>
 In the example above, foo_update_a() blocks until a grace period elapses.<br>
 This is quite simple, but in some cases one cannot afford to wait so<br>
 long -- there might be other high-priority work to be done.<br>
<br>
 In such cases, one uses call_rcu() rather than synchronize_rcu().<br>
-The call_rcu() API is as follows:<br>
+The call_rcu() API is as follows::<br>
<br>
        void call_rcu(struct rcu_head * head,<br>
                      void (*func)(struct rcu_head *head));<br>
@@ -481,7 +490,7 @@ The call_rcu() API is as follows:<br>
 This function invokes func(head) after a grace period has elapsed.<br>
 This invocation might happen from either softirq or process context,<br>
 so the function is not permitted to block.  The foo struct needs to<br>
-have an rcu_head structure added, perhaps as follows:<br>
+have an rcu_head structure added, perhaps as follows::<br>
<br>
        struct foo {<br>
                int a;<br>
@@ -490,7 +499,7 @@ have an rcu_head structure added, perhaps as follows:<br>
                struct rcu_head rcu;<br>
        };<br>
<br>
-The foo_update_a() function might then be written as follows:<br>
+The foo_update_a() function might then be written as follows::<br>
<br>
        /*<br>
         * Create a new struct foo that is the same as the one currently<br>
@@ -520,7 +529,7 @@ The foo_update_a() function might then be written as follows:<br>
                call_rcu(&amp;old_fp-&gt;rcu, foo_reclaim);<br>
        }<br>
<br>
-The foo_reclaim() function might appear as follows:<br>
+The foo_reclaim() function might appear as follows::<br>
<br>
        void foo_reclaim(struct rcu_head *rp)<br>
        {<br>
@@ -552,7 +561,7 @@ o   Use call_rcu() -after- removing a data element from an<br>
<br>
 If the callback for call_rcu() is not doing anything more than calling<br>
 kfree() on the structure, you can use kfree_rcu() instead of call_rcu()<br>
-to avoid having to write your own callback:<br>
+to avoid having to write your own callback::<br>
<br>
        kfree_rcu(old_fp, rcu);<br>
<br>
@@ -560,6 +569,7 @@ Again, see checklist.txt for additional rules governing the use of RCU.<br>
<br>
<br>
 5.  WHAT ARE SOME SIMPLE IMPLEMENTATIONS OF RCU?<br>
+------------------------------------------------<br>
<br>
 One of the nice things about RCU is that it has extremely simple &quot;toy&quot;<br>
 implementations that are a good first step towards understanding the<br>
@@ -591,7 +601,7 @@ you allow nested rcu_read_lock() calls, you can deadlock.<br>
 However, it is probably the easiest implementation to relate to, so is<br>
 a good starting point.<br>
<br>
-It is extremely simple:<br>
+It is extremely simple::<br>
<br>
        static DEFINE_RWLOCK(rcu_gp_mutex);<br>
<br>
@@ -614,7 +624,7 @@ It is extremely simple:<br>
<br>
 [You can ignore rcu_assign_pointer() and rcu_dereference() without missing<br>
 much.  But here are simplified versions anyway.  And whatever you do,<br>
-don&#39;t forget about them when submitting patches making use of RCU!]<br>
+don&#39;t forget about them when submitting patches making use of RCU!]::<br>
<br>
        #define rcu_assign_pointer(p, v) \<br>
        ({ \<br>
@@ -659,6 +669,7 @@ This section presents a &quot;toy&quot; RCU implementation that is based on<br>
 on features such as hotplug CPU and the ability to run in CONFIG_PREEMPT<br>
 kernels.  The definitions of rcu_dereference() and rcu_assign_pointer()<br>
 are the same as those shown in the preceding section, so they are omitted.<br>
+::<br>
<br>
        void rcu_read_lock(void) { }<br>
<br>
@@ -707,10 +718,12 @@ Quick Quiz #3:  If it is illegal to block in an RCU read-side<br>
<br>
<br>
 6.  ANALOGY WITH READER-WRITER LOCKING<br>
+--------------------------------------<br>
<br>
 Although RCU can be used in many different ways, a very common use of<br>
 RCU is analogous to reader-writer locking.  The following unified<br>
 diff shows how closely related RCU and reader-writer locking can be.<br>
+::<br>
<br>
        @@ -5,5 +5,5 @@ struct el {<br>
                int data;<br>
@@ -762,7 +775,7 @@ diff shows how closely related RCU and reader-writer locking can be.<br>
                return 0;<br>
         }<br>
<br>
-Or, for those who prefer a side-by-side listing:<br>
+Or, for those who prefer a side-by-side listing::<br>
<br>
  1 struct el {                          1 struct el {<br>
  2   struct list_head list;             2   struct list_head list;<br>
@@ -774,40 +787,44 @@ Or, for those who prefer a side-by-side listing:<br>
  8 rwlock_t listmutex;                  8 spinlock_t listmutex;<br>
  9 struct el head;                      9 struct el head;<br>
<br>
- 1 int search(long key, int *result)    1 int search(long key, int *result)<br>
- 2 {                                    2 {<br>
- 3   struct list_head *lp;              3   struct list_head *lp;<br>
- 4   struct el *p;                      4   struct el *p;<br>
- 5                                      5<br>
- 6   read_lock(&amp;listmutex);             6   rcu_read_lock();<br>
- 7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {<br>
- 8     if (p-&gt;key == key) {             8     if (p-&gt;key == key) {<br>
- 9       *result = p-&gt;data;             9       *result = p-&gt;data;<br>
-10       read_unlock(&amp;listmutex);      10       rcu_read_unlock();<br>
-11       return 1;                     11       return 1;<br>
-12     }                               12     }<br>
-13   }                                 13   }<br>
-14   read_unlock(&amp;listmutex);          14   rcu_read_unlock();<br>
-15   return 0;                         15   return 0;<br>
-16 }                                   16 }<br>
-<br>
- 1 int delete(long key)                 1 int delete(long key)<br>
- 2 {                                    2 {<br>
- 3   struct el *p;                      3   struct el *p;<br>
- 4                                      4<br>
- 5   write_lock(&amp;listmutex);            5   spin_lock(&amp;listmutex);<br>
- 6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {<br>
- 7     if (p-&gt;key == key) {             7     if (p-&gt;key == key) {<br>
- 8       list_del(&amp;p-&gt;list);            8       list_del_rcu(&amp;p-&gt;list);<br>
- 9       write_unlock(&amp;listmutex);      9       spin_unlock(&amp;listmutex);<br>
-                                       10       synchronize_rcu();<br>
-10       kfree(p);                     11       kfree(p);<br>
-11       return 1;                     12       return 1;<br>
-12     }                               13     }<br>
-13   }                                 14   }<br>
-14   write_unlock(&amp;listmutex);         15   spin_unlock(&amp;listmutex);<br>
-15   return 0;                         16   return 0;<br>
-16 }                                   17 }<br>
+::<br>
+<br>
+  1 int search(long key, int *result)    1 int search(long key, int *result)<br>
+  2 {                                    2 {<br>
+  3   struct list_head *lp;              3   struct list_head *lp;<br>
+  4   struct el *p;                      4   struct el *p;<br>
+  5                                      5<br>
+  6   read_lock(&amp;listmutex);             6   rcu_read_lock();<br>
+  7   list_for_each_entry(p, head, lp) { 7   list_for_each_entry_rcu(p, head, lp) {<br>
+  8     if (p-&gt;key == key) {             8     if (p-&gt;key == key) {<br>
+  9       *result = p-&gt;data;             9       *result = p-&gt;data;<br>
+ 10       read_unlock(&amp;listmutex);      10       rcu_read_unlock();<br>
+ 11       return 1;                     11       return 1;<br>
+ 12     }                               12     }<br>
+ 13   }                                 13   }<br>
+ 14   read_unlock(&amp;listmutex);          14   rcu_read_unlock();<br>
+ 15   return 0;                         15   return 0;<br>
+ 16 }                                   16 }<br>
+<br>
+::<br>
+<br>
+  1 int delete(long key)                 1 int delete(long key)<br>
+  2 {                                    2 {<br>
+  3   struct el *p;                      3   struct el *p;<br>
+  4                                      4<br>
+  5   write_lock(&amp;listmutex);            5   spin_lock(&amp;listmutex);<br>
+  6   list_for_each_entry(p, head, lp) { 6   list_for_each_entry(p, head, lp) {<br>
+  7     if (p-&gt;key == key) {             7     if (p-&gt;key == key) {<br>
+  8       list_del(&amp;p-&gt;list);            8       list_del_rcu(&amp;p-&gt;list);<br>
+  9       write_unlock(&amp;listmutex);      9       spin_unlock(&amp;listmutex);<br>
+                                        10       synchronize_rcu();<br>
+ 10       kfree(p);                     11       kfree(p);<br>
+ 11       return 1;                     12       return 1;<br>
+ 12     }                               13     }<br>
+ 13   }                                 14   }<br>
+ 14   write_unlock(&amp;listmutex);         15   spin_unlock(&amp;listmutex);<br>
+ 15   return 0;                         16   return 0;<br>
+ 16 }                                   17 }<br>
<br>
 Either way, the differences are quite small.  Read-side locking moves<br>
 to rcu_read_lock() and rcu_read_unlock, update-side locking moves from<br>
@@ -827,13 +844,14 @@ be used in place of synchronize_rcu().<br>
<br>
<br>
 7.  FULL LIST OF RCU APIs<br>
+-------------------------<br>
<br>
 The RCU APIs are documented in docbook-format header comments in the<br>
 Linux-kernel source code, but it helps to have a full list of the<br>
 APIs, since there does not appear to be a way to categorize them<br>
 in docbook.  Here is the list, by category.<br>
<br>
-RCU list traversal:<br>
+RCU list traversal::<br>
<br>
        list_entry_rcu<br>
        list_first_entry_rcu<br>
@@ -854,7 +872,7 @@ RCU list traversal:<br>
        hlist_bl_first_rcu<br>
        hlist_bl_for_each_entry_rcu<br>
<br>
-RCU pointer/list update:<br>
+RCU pointer/list udate::<br>
<br>
        rcu_assign_pointer<br>
        list_add_rcu<br>
@@ -876,7 +894,9 @@ RCU pointer/list update:<br>
        hlist_bl_del_rcu<br>
        hlist_bl_set_first_rcu<br>
<br>
-RCU:   Critical sections       Grace period            Barrier<br>
+RCU::<br>
+<br>
+       Critical sections       Grace period            Barrier<br>
<br>
        rcu_read_lock           synchronize_net         rcu_barrier<br>
        rcu_read_unlock         synchronize_rcu<br>
@@ -885,7 +905,9 @@ RCU:        Critical sections       Grace period            Barrier<br>
        rcu_dereference_check   kfree_rcu<br>
        rcu_dereference_protected<br>
<br>
-bh:    Critical sections       Grace period            Barrier<br>
+bh::<br>
+<br>
+       Critical sections       Grace period            Barrier<br>
<br>
        rcu_read_lock_bh        call_rcu                rcu_barrier<br>
        rcu_read_unlock_bh      synchronize_rcu<br>
@@ -896,7 +918,9 @@ bh: Critical sections       Grace period            Barrier<br>
        rcu_dereference_bh_protected<br>
        rcu_read_lock_bh_held<br>
<br>
-sched: Critical sections       Grace period            Barrier<br>
+sched::<br>
+<br>
+       Critical sections       Grace period            Barrier<br>
<br>
        rcu_read_lock_sched     call_rcu                rcu_barrier<br>
        rcu_read_unlock_sched   synchronize_rcu<br>
@@ -910,7 +934,9 @@ sched:      Critical sections       Grace period            Barrier<br>
        rcu_read_lock_sched_held<br>
<br>
<br>
-SRCU:  Critical sections       Grace period            Barrier<br>
+SRCU::<br>
+<br>
+       Critical sections       Grace period            Barrier<br>
<br>
        srcu_read_lock          call_srcu               srcu_barrier<br>
        srcu_read_unlock        synchronize_srcu<br>
@@ -918,13 +944,14 @@ SRCU:     Critical sections       Grace period            Barrier<br>
        srcu_dereference_check<br>
        srcu_read_lock_held<br>
<br>
-SRCU:  Initialization/cleanup<br>
+SRCU: Initialization/cleanup::<br>
+<br>
        DEFINE_SRCU<br>
        DEFINE_STATIC_SRCU<br>
        init_srcu_struct<br>
        cleanup_srcu_struct<br>
<br>
-All:  lockdep-checked RCU-protected pointer access<br>
+All: lockdep-checked RCU-protected pointer access::<br>
<br>
        rcu_access_pointer<br>
        rcu_dereference_raw<br>
@@ -976,6 +1003,7 @@ the right tool for your job.<br>
<br>
<br>
 8.  ANSWERS TO QUICK QUIZZES<br>
+----------------------------<br>
<br>
 Quick Quiz #1: Why is this argument naive?  How could a deadlock<br>
                occur when using this algorithm in a real-world Linux<br></blockquote><div><br></div><div>Here, the formatting is not proper. In the rst file, the question should be added in the next line after Quick Quiz #1. Currently, half of the question appears in bold and the rest half does not.</div><div>Also, as followed in all the documents there should be a cross-reference to the answer to this question. As this document is quite big having references would be helpful.</div><div>The same applies to all other quick quiz questions in this document and in the Answers section as well the questions do not appear properly, half in bold text and half not bold.</div><div><br></div><div>Apart from this, the other added changes look good!</div><div><br></div><div>Thank you</div><div>Madhuparna</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
-- <br>
2.20.1<br>
<br>
_______________________________________________<br>
Linux-kernel-mentees mailing list<br>
<a href="mailto:Linux-kernel-mentees@lists.linuxfoundation.org" target="_blank">Linux-kernel-mentees@lists.linuxfoundation.org</a><br>
<a href="https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees" rel="noreferrer" target="_blank">https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees</a><br>
</blockquote></div></div><div hspace="streak-pt-mark" style="max-height:1px"><img alt="" style="width: 0px; max-height: 0px; overflow: hidden;" src="https://mailfoogae.appspot.com/t?sender=abWFkaHVwYXJuYWJob3dtaWswNEBnbWFpbC5jb20%3D&amp;type=zerocontent&amp;guid=8fec4e47-6422-4486-a303-a30685f7265d"><font color="#ffffff" size="1">ᐧ</font></div>
</blockquote></div></div>

[-- Attachment #2: Type: text/plain, Size: 201 bytes --]

_______________________________________________
Linux-kernel-mentees mailing list
Linux-kernel-mentees@lists.linuxfoundation.org
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees

^ permalink raw reply	[flat|nested] 23+ messages in thread

end of thread, back to index

Thread overview: 23+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-10-30 23:31 [Linux-kernel-mentees] [PATCH] Doc: convert whatisRCU.txt to rst tranmanphong at gmail.com (Phong Tran)
2019-10-30 23:31 ` tranmanphong
2019-10-31 22:54 ` paulmck at kernel.org (Paul E. McKenney)
2019-10-31 22:54   ` Paul E. McKenney
2019-10-31 22:54   ` paulmck
2019-11-01  1:17   ` tranmanphong at gmail.com (Phong Tran)
2019-11-01  1:17     ` Phong Tran
2019-11-01  1:17     ` tranmanphong
2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
2019-11-01  7:53       ` paulmck
2019-11-01  7:53       ` Paul E. McKenney
2019-11-01  3:33   ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
2019-11-01  3:33     ` madhuparnabhowmik04
2019-11-01  3:33     ` Madhuparna Bhowmik
2019-11-01  7:53     ` paulmck at kernel.org (Paul E. McKenney)
2019-11-01  7:53       ` paulmck
2019-11-01  7:53       ` Paul E. McKenney
2019-11-02  8:31 ` madhuparnabhowmik04 at gmail.com (Madhuparna Bhowmik)
2019-11-02  8:31   ` madhuparnabhowmik04
2019-11-02  8:31   ` Madhuparna Bhowmik
2019-11-02 12:00   ` tranmanphong at gmail.com (Phong Tran)
2019-11-02 12:00     ` Phong Tran
2019-11-02 12:00     ` tranmanphong

Linux Kernel Mentees Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-kernel-mentees/0 linux-kernel-mentees/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-kernel-mentees linux-kernel-mentees/ https://lore.kernel.org/linux-kernel-mentees \
		linux-kernel-mentees@lists.linuxfoundation.org
	public-inbox-index linux-kernel-mentees

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.linuxfoundation.lists.linux-kernel-mentees


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git