docs: RCU: Convert rcuref.txt to ReST

- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

Documentation/RCU/index.rst

@@ -18,6 +18,7 @@ RCU concepts
    whatisRCU
    rcu
    rculist_nulls
+   rcuref
    torture
    listRCU
    NMI-RCU

Documentation/RCU/rcuref.rst

@@ -1,4 +1,8 @@
-Reference-count design for elements of lists/arrays protected by RCU.
+.. SPDX-License-Identifier: GPL-2.0
+
+====================================================================
+Reference-count design for elements of lists/arrays protected by RCU
+====================================================================
 
 
 Please note that the percpu-ref feature is likely your first
@@ -12,10 +16,11 @@ please read on.
 Reference counting on elements of lists which are protected by traditional
 reader/writer spinlocks or semaphores are straightforward:
 
-CODE LISTING A:
-1.				2.
-add()				search_and_reference()
-{				{
+CODE LISTING A::
+
+    1.					    2.
+    add()				    search_and_reference()
+    {					    {
 	alloc_object				read_lock(&list_lock);
 	...					search_for_element
 	atomic_set(&el->rc, 1);			atomic_inc(&el->rc);
@@ -23,16 +28,16 @@ add()				search_and_reference()
 	add_element				read_unlock(&list_lock);
 	...					...
 	write_unlock(&list_lock);	   }
-}
+    }
 
-3.					4.
-release_referenced()			delete()
-{					{
+    3.					    4.
+    release_referenced()		    delete()
+    {					    {
 	...					write_lock(&list_lock);
 	if(atomic_dec_and_test(&el->rc))	...
 	    kfree(el);
 	...					remove_element
-}					    write_unlock(&list_lock);
+    }						write_unlock(&list_lock);
 						...
 						if (atomic_dec_and_test(&el->rc))
 						    kfree(el);
@@ -46,10 +51,11 @@ search_and_reference() could potentially hold reference to an element which
 has already been deleted from the list/array.  Use atomic_inc_not_zero()
 in this scenario as follows:
 
-CODE LISTING B:
-1.					2.
-add()					search_and_reference()
-{					{
+CODE LISTING B::
+
+    1.					    2.
+    add()				    search_and_reference()
+    {					    {
 	alloc_object				rcu_read_lock();
 	...					search_for_element
 	atomic_set(&el->rc, 1);			if (!atomic_inc_not_zero(&el->rc)) {
@@ -58,15 +64,15 @@ add()					search_and_reference()
 	add_element				}
 	...					...
 	spin_unlock(&list_lock);		rcu_read_unlock();
-}					}
-3.					4.
-release_referenced()			delete()
-{					{
+    }					    }
+    3.					    4.
+    release_referenced()		    delete()
+    {					    {
 	...					spin_lock(&list_lock);
 	if (atomic_dec_and_test(&el->rc))	...
 	    call_rcu(&el->head, el_free);	remove_element
 	...					spin_unlock(&list_lock);
-} 					    ...
+    }						...
 						if (atomic_dec_and_test(&el->rc))
 						    call_rcu(&el->head, el_free);
 						...
@@ -82,10 +88,11 @@ search_and_reference() code path.  In such cases, the
 atomic_dec_and_test() may be moved from delete() to el_free()
 as follows:
 
-CODE LISTING C:
-1.					2.
-add()					search_and_reference()
-{					{
+CODE LISTING C::
+
+    1.					    2.
+    add()				    search_and_reference()
+    {					    {
 	alloc_object				rcu_read_lock();
 	...					search_for_element
 	atomic_set(&el->rc, 1);			atomic_inc(&el->rc);
@@ -94,20 +101,20 @@ add()					search_and_reference()
 	add_element				rcu_read_unlock();
 	...				    }
 	spin_unlock(&list_lock);	    4.
-}					delete()
-3.					{
-release_referenced()			    spin_lock(&list_lock);
-{					    ...
+    }					    delete()
+    3.					    {
+    release_referenced()			spin_lock(&list_lock);
+    {						...
 	...					remove_element
 	if (atomic_dec_and_test(&el->rc))	spin_unlock(&list_lock);
 	    kfree(el);				...
 	...					call_rcu(&el->head, el_free);
-} 					    ...
-5.					}
-void el_free(struct rcu_head *rhp)
-{
+    }						...
+    5.					    }
+    void el_free(struct rcu_head *rhp)
+    {
 	release_referenced();
-}
+    }
 
 The key point is that the initial reference added by add() is not removed
 until after a grace period has elapsed following removal.  This means that
@@ -130,11 +137,11 @@ the eventual invocation of kfree(), which is usually not a problem on
 modern computer systems, even the small ones.
 
 In cases where delete() can sleep, synchronize_rcu() can be called from
-delete(), so that el_free() can be subsumed into delete as follows:
+delete(), so that el_free() can be subsumed into delete as follows::
 
-4.
-delete()
-{
+    4.
+    delete()
+    {
 	spin_lock(&list_lock);
 	...
 	remove_element
@@ -144,7 +151,7 @@ delete()
 	if (atomic_dec_and_test(&el->rc))
 	    kfree(el);
 	...
-}
+    }
 
 As additional examples in the kernel, the pattern in listing C is used by
 reference counting of struct pid, while the pattern in listing B is used by