Updates to RCU documentation

diff -urpN -X ../dontdiff linux-2.5/Documentation/RCU/UP.txt linux-2.5-rcudoc/Documentation/RCU/UP.txt
@@ -50,8 +50,8 @@ this case?
 
 Summary
 
-Permitting call_rcu() to immediatly invoke its arguments or permitting
-synchronize_kernel() to immediatly return breaks RCU, even on a UP system.
+Permitting call_rcu() to immediately invoke its arguments or permitting
+synchronize_kernel() to immediately return breaks RCU, even on a UP system.
 So do not do it!  Even on a UP system, the RCU infrastructure -must-
 respect grace periods.
 

141 lines not on this page · raw message

diff -urpN -X ../dontdiff linux-2.5/Documentation/RCU/listRCU.txt linux-2.5-rcudoc/Documentation/RCU/listRCU.txt
@@ -18,8 +18,8 @@ equipment outside of the computer, it wi
 Therefore, once the route has been computed, there is no need to hold
 the routing table static during transmission of the packet.  After all,
 you can hold the routing table static all you want, but that won't keep
-the external internet from changing, and it is the state of the external
-internet that really matters.  In addition, routing entries are typically
+the external Internet from changing, and it is the state of the external
+Internet that really matters.  In addition, routing entries are typically
 added or deleted, rather than being modified in place.
 
 A straightforward example of this use of RCU may be found in the

@@ -195,7 +195,7 @@ RCU ("read-copy update") its name.  The 
 			if (!audit_compare_rule(rule, &e->rule)) {
 				ne = kmalloc(sizeof(*entry), GFP_ATOMIC);
 				if (ne == NULL)
-					return _ENOMEM;
+					return -ENOMEM;
 				audit_copy_rule(&ne->rule, &e->rule);
 				ne->rule.action = newaction;
 				ne->rule.file_count = newfield_count;

@@ -255,6 +255,12 @@ as follows:
 		rcu_read_unlock();
 		return AUDIT_BUILD_CONTEXT;
 	}
+
+Note that this example assumes that entries are only added and deleted.
+Additional mechanism is required to deal correctly with the
+update-in-place performed by audit_upd_rule().  For one thing,
+audit_upd_rule() would need additional memory barriers to ensure
+that the list_add_rcu() was really executed before the list_del_rcu().
 
 The audit_del_rule() function would need to set the "deleted"
 flag under the spinlock as follows:

diff -urpN -X ../dontdiff linux-2.5/Documentation/RCU/rcu.txt linux-2.5-rcudoc/Documentation/RCU/rcu.txt
@@ -1,20 +1,19 @@
 RCU Concepts
 
 
-The basic idea behind RCU is to split destructive operations into two
-parts, one that makes anyone from seeing the data item being destroyed,
-and one that actually carries out the destruction.  A "grace period"
-must elapse between the two parts, and this grace period must be long
-enough that any readers accessing the item being deleted have since
-dropped their references.  For example, an RCU-protected deletion from a
-linked list would first remove the item from the list, wait for a grace
-period to elapse, then free the element.  See the listRCU.txt file for
-more information on using RCU with linked lists.
+The basic idea behind RCU (read-copy update) is to split destructive
+operations into two parts, one that prevents anyone from seeing the data
+item being destroyed, and one that actually carries out the destruction.
+A "grace period" must elapse between the two parts, and this grace period
+must be long enough that any readers accessing the item being deleted have
+since dropped their references.  For example, an RCU-protected deletion
+from a linked list would first remove the item from the list, wait for
+a grace period to elapse, then free the element.  See the listRCU.txt
+file for more information on using RCU with linked lists.
 
 
 Frequently Asked Questions
 
-
 o	Why would anyone want to use RCU?
 
 	The advantage of RCU's two-part approach is that RCU readers need

@@ -25,7 +24,6 @@ o	Why would anyone want to use RCU?
 	in read-mostly situations.  The fact that RCU readers need not
 	acquire locks can also greatly simplify deadlock-avoidance code.
 
-
 o	How can the updater tell when a grace period has completed
 	if the RCU readers give no indication when they are done?
 

@@ -50,6 +48,19 @@ o	How can I see where RCU is currently u
 o	What guidelines should I follow when writing code that uses RCU?
 
 	See the checklist.txt file in this directory.
+
+o	Why the name "RCU"?
+
+	"RCU" stands for "read-copy update".  The file listRCU.txt has
+	more information on where this name came from, search for
+	"read-copy update" to find it.
+
+o	I hear that RCU is patented?  What is with that?
+
+	Yes, it is.  There are several known patents related to RCU,
+	search for the string "Patent" in RTFP.txt to find them.
+	Of these, one was allowed to lapse by the assignee, and the
+	others have been contributed to the Linux kernel under GPL.
 
 o	Where can I find more information on RCU?
 

diff -urpN -X ../dontdiff linux-2.5/Documentation/RCU/RTFP.txt linux-2.5-rcudoc/Documentation/RCU/RTFP.txt
@@ -202,10 +202,33 @@ Utilizing Execution History and Thread M
 ,institution="US Patent and Trademark Office"
 ,address="Washington, DC"
 ,year="1995"
-,number="US Patent 5,442,758"
+,number="US Patent 5,442,758 (contributed under GPL)"
 ,month="August"
 }
 
+@techreport{Slingwine97
+,author="John D. Slingwine and Paul E. McKenney"
+,title="Method for maintaining data coherency using thread
+activity summaries in a multicomputer system"
+,institution="US Patent and Trademark Office"
+,address="Washington, DC"
+,year="1997"
+,number="US Patent 5,608,893 (contributed under GPL)"
+,month="March"
+}
+
+@techreport{Slingwine98
+,author="John D. Slingwine and Paul E. McKenney"
+,title="Apparatus and method for achieving reduced overhead
+mutual exclusion and maintaining coherency in a multiprocessor
+system utilizing execution history and thread monitoring"
+,institution="US Patent and Trademark Office"
+,address="Washington, DC"
+,year="1998"
+,number="US Patent 5,727,209 (contributed under GPL)"
+,month="March"
+}
+
 @Conference{McKenney98
 ,Author="Paul E. McKenney and John D. Slingwine"
 ,Title="Read-Copy Update: Using Execution History to Solve Concurrency

@@ -227,6 +250,18 @@ Operating System Design and Implementati
 ,Year="1999"
 ,pages="87-100"
 ,Address="New Orleans, LA"
+}
+
+@techreport{Slingwine01
+,author="John D. Slingwine and Paul E. McKenney"
+,title="Apparatus and method for achieving reduced overhead
+mutual exclusion and maintaining coherency in a multiprocessor
+system utilizing execution history and thread monitoring"
+,institution="US Patent and Trademark Office"
+,address="Washington, DC"
+,year="2001"
+,number="US Patent 5,219,690 (contributed under GPL)"
+,month="April"
 }
 
 @Conference{McKenney01a