Hello!
This series contains documentation updates:
1. documentation/rcu: Fix typo, courtesy of Tycho Andersen.
2. docs/RCU: Add the missing rcu_read_unlock(), courtesy of Alan
Huang.
3. Docs/RCU/rculist_nulls: Fix trivial coding style, courtesy of
SeongJae Park.
4. Docs/RCU/rculist_nulls: Assign 'obj' before use from the examples,
courtesy of SeongJae Park.
5. Docs/RCU/rculist_nulls: Specify type of the object in examples,
courtesy of SeongJae Park.
6. Docs/RCU/rculist_nulls: Fix hlist_[nulls]_head field names of
'obj', courtesy of SeongJae Park.
7. Docs/RCU/rculist_nulls: Fix text about atomic_set_release(),
courtesy of SeongJae Park.
Thanx, Paul
------------------------------------------------------------------------
Documentation/RCU/rculist_nulls.rst | 38 +++++++++++++++++++++++-----------
b/Documentation/RCU/lockdep-splat.rst | 2 -
b/Documentation/RCU/rculist_nulls.rst | 4 ++-
3 files changed, 30 insertions(+), 14 deletions(-)
From: SeongJae Park <[email protected]>
Lookup example code snippets in rculist_nulls.rst are using 'obj'
without assignment. Fix the code to assign it properly.
Signed-off-by: SeongJae Park <[email protected]>
Reviewed-by: Joel Fernandes (Google) <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
---
Documentation/RCU/rculist_nulls.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
index 25b739885cfa..4d6f077552ed 100644
--- a/Documentation/RCU/rculist_nulls.rst
+++ b/Documentation/RCU/rculist_nulls.rst
@@ -56,7 +56,7 @@ but a version with an additional memory barrier (smp_rmb())
struct hlist_node *node, *next;
for (pos = rcu_dereference((head)->first);
pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
- ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
+ ({ obj = hlist_entry(pos, typeof(*obj), member); 1; });
pos = rcu_dereference(next))
if (obj->key == key)
return obj;
@@ -68,7 +68,7 @@ And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb()::
struct hlist_node *node;
for (pos = rcu_dereference((head)->first);
pos && ({ prefetch(pos->next); 1; }) &&
- ({ tpos = hlist_entry(pos, typeof(*tpos), member); 1; });
+ ({ obj = hlist_entry(pos, typeof(*obj), member); 1; });
pos = rcu_dereference(pos->next))
if (obj->key == key)
return obj;
--
2.40.1
From: Tycho Andersen <[email protected]>
s/slat/splat/
Signed-off-by: Tycho Andersen <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
---
Documentation/RCU/lockdep-splat.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/RCU/lockdep-splat.rst b/Documentation/RCU/lockdep-splat.rst
index 2a5c79db57dc..bcbc4b3c88d7 100644
--- a/Documentation/RCU/lockdep-splat.rst
+++ b/Documentation/RCU/lockdep-splat.rst
@@ -10,7 +10,7 @@ misuses of the RCU API, most notably using one of the rcu_dereference()
family to access an RCU-protected pointer without the proper protection.
When such misuse is detected, an lockdep-RCU splat is emitted.
-The usual cause of a lockdep-RCU slat is someone accessing an
+The usual cause of a lockdep-RCU splat is someone accessing an
RCU-protected data structure without either (1) being in the right kind of
RCU read-side critical section or (2) holding the right update-side lock.
This problem can therefore be serious: it might result in random memory
--
2.40.1
From: SeongJae Park <[email protected]>
The document says we can avoid extra _release() in insert function when
hlist_nulls is used, but that's not true[1]. Drop it.
[1] https://lore.kernel.org/rcu/46440869-644a-4982-b790-b71b43976c66@paulmck-laptop/
Signed-off-by: SeongJae Park <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
---
Documentation/RCU/rculist_nulls.rst | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
index 1fb086066377..21e40fcc08de 100644
--- a/Documentation/RCU/rculist_nulls.rst
+++ b/Documentation/RCU/rculist_nulls.rst
@@ -140,8 +140,7 @@ very very fast (before the end of RCU grace period)
Avoiding extra smp_rmb()
========================
-With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
-and extra _release() in insert function.
+With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup().
For example, if we choose to store the slot number as the 'nulls'
end-of-list marker for each slot of the hash table, we can detect
@@ -196,6 +195,9 @@ Note that using hlist_nulls means the type of 'obj_node' field of
2) Insert algorithm
-------------------
+Same to the above one, but uses hlist_nulls_add_head_rcu() instead of
+hlist_add_head_rcu().
+
::
/*
--
2.40.1
From: SeongJae Park <[email protected]>
The example code snippets on rculist_nulls.rst are assuming 'obj' to
have the 'hlist_head' or 'hlist_nulls_head' field named 'obj_node', but
a sentence and some code snippets are wrongly calling
'obj->obj_node.next' as 'obj->obj_next', or 'obj->obj_node' as 'member'.
Fix it.
Signed-off-by: SeongJae Park <[email protected]>
Signed-off-by: Paul E. McKenney <[email protected]>
---
Documentation/RCU/rculist_nulls.rst | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/RCU/rculist_nulls.rst b/Documentation/RCU/rculist_nulls.rst
index 479cedfec446..1fb086066377 100644
--- a/Documentation/RCU/rculist_nulls.rst
+++ b/Documentation/RCU/rculist_nulls.rst
@@ -65,7 +65,7 @@ but a version with an additional memory barrier (smp_rmb())
struct hlist_node *node, *next;
for (pos = rcu_dereference((head)->first);
pos && ({ next = pos->next; smp_rmb(); prefetch(next); 1; }) &&
- ({ obj = hlist_entry(pos, typeof(*obj), member); 1; });
+ ({ obj = hlist_entry(pos, typeof(*obj), obj_node); 1; });
pos = rcu_dereference(next))
if (obj->key == key)
return obj;
@@ -77,7 +77,7 @@ And note the traditional hlist_for_each_entry_rcu() misses this smp_rmb()::
struct hlist_node *node;
for (pos = rcu_dereference((head)->first);
pos && ({ prefetch(pos->next); 1; }) &&
- ({ obj = hlist_entry(pos, typeof(*obj), member); 1; });
+ ({ obj = hlist_entry(pos, typeof(*obj), obj_node); 1; });
pos = rcu_dereference(pos->next))
if (obj->key == key)
return obj;
@@ -97,7 +97,7 @@ Quoting Corey Minyard::
2) Insertion algorithm
----------------------
-We need to make sure a reader cannot read the new 'obj->obj_next' value
+We need to make sure a reader cannot read the new 'obj->obj_node.next' value
and previous value of 'obj->key'. Otherwise, an item could be deleted
from a chain, and inserted into another chain. If new chain was empty
before the move, 'next' pointer is NULL, and lockless reader can not
@@ -165,7 +165,7 @@ Note that using hlist_nulls means the type of 'obj_node' field of
head = &table[slot];
begin:
rcu_read_lock();
- hlist_nulls_for_each_entry_rcu(obj, node, head, member) {
+ hlist_nulls_for_each_entry_rcu(obj, node, head, obj_node) {
if (obj->key == key) {
if (!try_get_ref(obj)) { // might fail for free objects
rcu_read_unlock();
--
2.40.1