Documentation updates for v5.3
Subsystems (2)
cover Documentation updates for v5.3
Hello!
This series provides a couple of documentation updates:
1. Document real world rcuref examples from the Linux kernel,
courtesy of Joel Fernandes.
2. Fixup definition of rcupdate.rcu_task_stall_timeout, courtesy
of Zhenzhong Duan.
Thanx, Paul
------------------------------------------------------------------------
rcuref.txt | 21 ++++++++++++++++++++- stallwarn.txt | 2 +- 2 files changed, 21 insertions(+), 2 deletions(-)
PATCH 1/2 doc/rcuref: Document real world examples in kernel
From: "Joel Fernandes (Google)" <[email protected]>
Document similar real world examples in the kernel corresponding to the second and third code snippets. Also correct an issue in release_referenced() in the code snippet example.
--- Documentation/RCU/rcuref.txt | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-)
Documentation/RCU/rcuref.txt +20 -1
@@ -12,6 +12,7 @@ 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() { {
@@ -28,7 +29,8 @@ add() search_and_reference() release_referenced() delete() { { ... write_lock(&list_lock); - atomic_dec(&el->rc, relfunc) ... + if(atomic_dec_and_test(&el->rc)) ... + kfree(el); ... remove_element } write_unlock(&list_lock); ...
@@ -44,6 +46,7 @@ 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() { {
@@ -79,6 +82,7 @@ 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() { {
@@ -114,6 +118,17 @@ element can therefore safely be freed. This in turn guarantees that if any reader finds the element, that reader may safely acquire a reference without checking the value of the reference counter. +A clear advantage of the RCU-based pattern in listing C over the one +in listing B is that any call to search_and_reference() that locates +a given object will succeed in obtaining a reference to that object, +even given a concurrent invocation of delete() for that same object. +Similarly, a clear advantage of both listings B and C over listing A is +that a call to delete() is not delayed even if there are an arbitrarily +large number of calls to search_and_reference() searching for the same +object that delete() was invoked on. Instead, all that is delayed is +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:
@@ -130,3 +145,7 @@ delete() 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 +struct posix_acl.
Signature · 1 line
2.17.1
PATCH 2/2 doc: Fixup definition of rcupdate.rcu_task_stall_timeout
In reply to Paul E. McKenneyFrom: Zhenzhong Duan <[email protected]>
A positive value of rcupdate.rcu_task_stall_timeout is an interval in seconds rather than jiffies.
--- Documentation/RCU/stallwarn.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/stallwarn.txt +1 -1
@@ -153,7 +153,7 @@ rcupdate.rcu_task_stall_timeout This boot/sysfs parameter controls the RCU-tasks stall warning interval. A value of zero or less suppresses RCU-tasks stall warnings. A positive value sets the stall-warning interval - in jiffies. An RCU-tasks stall warning starts with the line: + in seconds. An RCU-tasks stall warning starts with the line: INFO: rcu_tasks detected stalls on tasks:
Signature · 1 line
2.17.1