Documentation updates for v5.9
Subsystems (6)
Paul E. McKenney
maintainercover Documentation updates for v5.9
Hello!
This series provides documentation updates.
1-7. Convert Documentation/RCU files to .rst, courtesy of Mauro
Carvalho Chehab.
8. RCU: Don't duplicate chapter names in rculist_nulls.rst, courtesy
of Mauro Carvalho Chehab.
9. Timer problems can cause RCU CPU stall warnings.
10. Tasks RCU must protect instructions before trampoline.
Thanx, Paul
------------------------------------------------------------------------
Documentation/RCU/rculist_nulls.txt | 172 ------------ b/Documentation/RCU/Design/Requirements/Requirements.rst | 7 b/Documentation/RCU/checklist.rst | 17 - b/Documentation/RCU/index.rst | 9 b/Documentation/RCU/lockdep-splat.rst | 109 ++++---- b/Documentation/RCU/lockdep.rst | 12 b/Documentation/RCU/rculist_nulls.rst | 200 +++++++++++++++ b/Documentation/RCU/rcuref.rst | 199 +++++++------- b/Documentation/RCU/stallwarn.rst | 62 +++- b/Documentation/RCU/torture.rst | 117 ++++---- b/Documentation/locking/locktorture.rst | 2 b/MAINTAINERS | 4 b/include/linux/rculist_nulls.h | 2 b/kernel/rcu/rcutorture.c | 2 b/kernel/rcu/tree_stall.h | 4 b/net/core/sock.c | 4 16 files changed, 509 insertions(+), 413 deletions(-)
[email protected]
maintainerPATCH 1/10 docs: RCU: Convert checklist.txt to ReST
From: Mauro Carvalho Chehab <[email protected]>
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Use the right list markups;
- Add it to RCU/index.rst.
---
Documentation/RCU/{checklist.txt => checklist.rst} | 17 ++++++++++++-----
Documentation/RCU/index.rst | 3 +++
2 files changed, 15 insertions(+), 5 deletions(-)
rename Documentation/RCU/{checklist.txt => checklist.rst} (98%)Documentation/RCU/checklist.rst renamed from Documentation/RCU/checklist.txt +12 -5
@@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================ Review Checklist for RCU Patches +================================ This document contains a checklist for producing and reviewing patches
@@ -411,18 +415,21 @@ over a rather long period of time, but improvements are always welcome! __rcu sparse checks to validate your RCU code. These can help find problems as follows: - CONFIG_PROVE_LOCKING: check that accesses to RCU-protected data + CONFIG_PROVE_LOCKING: + check that accesses to RCU-protected data structures are carried out under the proper RCU read-side critical section, while holding the right combination of locks, or whatever other conditions are appropriate. - CONFIG_DEBUG_OBJECTS_RCU_HEAD: check that you don't pass the + CONFIG_DEBUG_OBJECTS_RCU_HEAD: + check that you don't pass the same object to call_rcu() (or friends) before an RCU grace period has elapsed since the last time that you passed that same object to call_rcu() (or friends). - __rcu sparse checks: tag the pointer to the RCU-protected data + __rcu sparse checks: + tag the pointer to the RCU-protected data structure with __rcu, and sparse will warn you if you access that pointer without the services of one of the variants of rcu_dereference().
@@ -442,8 +449,8 @@ over a rather long period of time, but improvements are always welcome! You instead need to use one of the barrier functions: - o call_rcu() -> rcu_barrier() - o call_srcu() -> srcu_barrier() + - call_rcu() -> rcu_barrier() + - call_srcu() -> srcu_barrier() However, these barrier functions are absolutely -not- guaranteed to wait for a grace period. In fact, if there are no call_rcu()
Documentation/RCU/index.rst +3 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. _rcu_concepts: ============
@@ -8,6 +10,7 @@ RCU concepts :maxdepth: 3 arrayRCU + checklist rcubarrier rcu_dereference whatisRCU
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 2/10 docs: RCU: Convert lockdep-splat.txt to ReST
In reply to Paul E. McKenneyFrom: Mauro Carvalho Chehab <[email protected]>
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
.../RCU/{lockdep-splat.txt => lockdep-splat.rst} | 109 +++++++++++----------
2 files changed, 58 insertions(+), 52 deletions(-)
rename Documentation/RCU/{lockdep-splat.txt => lockdep-splat.rst} (54%)Documentation/RCU/index.rst +1 -0
@@ -11,6 +11,7 @@ RCU concepts arrayRCU checklist + lockdep-splat rcubarrier rcu_dereference whatisRCU
Documentation/RCU/lockdep-splat.rst renamed from Documentation/RCU/lockdep-splat.txt +57 -52
136 lines not on this page · raw message
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 3/10 docs: RCU: Convert lockdep.txt to ReST
In reply to Paul E. McKenneyFrom: Mauro Carvalho Chehab <[email protected]>
- Add a SPDX header;
- Adjust document title;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
Documentation/RCU/{lockdep.txt => lockdep.rst} | 12 ++++++++----
2 files changed, 9 insertions(+), 4 deletions(-)
rename Documentation/RCU/{lockdep.txt => lockdep.rst} (96%)Documentation/RCU/index.rst +1 -0
@@ -11,6 +11,7 @@ RCU concepts arrayRCU checklist + lockdep lockdep-splat rcubarrier rcu_dereference
Documentation/RCU/lockdep.rst renamed from Documentation/RCU/lockdep.txt +8 -4
@@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== RCU and lockdep checking +======================== All flavors of RCU have lockdep checking available, so that lockdep is aware of when each task enters and leaves any flavor of RCU read-side
@@ -8,7 +12,7 @@ tracking to include RCU state, which can sometimes help when debugging deadlocks and the like. In addition, RCU provides the following primitives that check lockdep's -state: +state:: rcu_read_lock_held() for normal RCU. rcu_read_lock_bh_held() for RCU-bh.
@@ -63,7 +67,7 @@ checking of rcu_dereference() primitives: The rcu_dereference_check() check expression can be any boolean expression, but would normally include a lockdep expression. However, any boolean expression can be used. For a moderately ornate example, -consider the following: +consider the following:: file = rcu_dereference_check(fdt->fd[fd], lockdep_is_held(&files->file_lock) ||
@@ -82,7 +86,7 @@ RCU read-side critical sections, in case (2) the ->file_lock prevents any change from taking place, and finally, in case (3) the current task is the only task accessing the file_struct, again preventing any change from taking place. If the above statement was invoked only from updater -code, it could instead be written as follows: +code, it could instead be written as follows:: file = rcu_dereference_protected(fdt->fd[fd], lockdep_is_held(&files->file_lock) ||
@@ -105,7 +109,7 @@ false and they are called from outside any RCU read-side critical section. For example, the workqueue for_each_pwq() macro is intended to be used either within an RCU read-side critical section or with wq->mutex held. -It is thus implemented as follows: +It is thus implemented as follows:: #define for_each_pwq(pwq, wq) list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 4/10 docs: RCU: Convert rculist_nulls.txt to ReST
In reply to Paul E. McKenneyFrom: Mauro Carvalho Chehab <[email protected]>
- 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.
--- Documentation/RCU/index.rst | 1 + Documentation/RCU/rculist_nulls.rst | 194 ++++++++++++++++++++++++++++++++++++ Documentation/RCU/rculist_nulls.txt | 172 -------------------------------- include/linux/rculist_nulls.h | 2 +- net/core/sock.c | 4 +- 5 files changed, 198 insertions(+), 175 deletions(-) create mode 100644 Documentation/RCU/rculist_nulls.rst delete mode 100644 Documentation/RCU/rculist_nulls.txt
Documentation/RCU/index.rst +1 -0
@@ -17,6 +17,7 @@ RCU concepts rcu_dereference whatisRCU rcu + rculist_nulls listRCU NMI-RCU UP
Documentation/RCU/rculist_nulls.rst new file +194 -0
194 lines not on this page · raw message
Documentation/RCU/rculist_nulls.txt deleted +0 -172
172 lines not on this page · raw message
include/linux/rculist_nulls.h +1 -1
@@ -162,7 +162,7 @@ static inline void hlist_nulls_add_fake(struct hlist_nulls_node *n)* The barrier() is needed to make sure compiler doesn't cache first element [1], * as this loop can be restarted [2] * [1] Documentation/core-api/atomic_ops.rst around line 114 -* [2] Documentation/RCU/rculist_nulls.txt around line 146 +* [2] Documentation/RCU/rculist_nulls.rst around line 146 */ #define hlist_nulls_for_each_entry_rcu (tpos, pos, head, member) \ for (({barrier();}), \
net/core/sock.c +2 -2
@@ -1972,7 +1972,7 @@ struct sock *sk_clone_lock(const struct sock *sk, const gfp_t priority)/* * Before updating sk_refcnt, we must commit prior changes to memory -* (Documentation/RCU/rculist_nulls.txt for details) +* (Documentation/RCU/rculist_nulls.rst for details) */ smp_wmb ();refcount_set (&newsk->sk_refcnt,2 );
@@ -3033,7 +3033,7 @@ void sock_init_data(struct socket *sock, struct sock *sk)sk_rx_queue_clear (sk);/* * Before updating sk_refcnt, we must commit prior changes to memory -* (Documentation/RCU/rculist_nulls.txt for details) +* (Documentation/RCU/rculist_nulls.rst for details) */ smp_wmb ();refcount_set (&sk->sk_refcnt,1 );
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 5/10 docs: RCU: Convert torture.txt to ReST
In reply to Paul E. McKenneyFrom: Mauro Carvalho Chehab <[email protected]>
- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
Documentation/RCU/{torture.txt => torture.rst} | 117 ++++++++++++++-----------
Documentation/locking/locktorture.rst | 2 +-
MAINTAINERS | 4 +-
kernel/rcu/rcutorture.c | 2 +-
5 files changed, 69 insertions(+), 57 deletions(-)
rename Documentation/RCU/{torture.txt => torture.rst} (76%)Documentation/RCU/index.rst +1 -0
@@ -18,6 +18,7 @@ RCU concepts whatisRCU rcu rculist_nulls + torture listRCU NMI-RCU UP
Documentation/RCU/torture.rst renamed from Documentation/RCU/torture.txt +64 -53
251 lines not on this page · raw message
Documentation/locking/locktorture.rst +1 -1
@@ -166,4 +166,4 @@ checked for such errors. The "rmmod" command forces a "SUCCESS", two are self-explanatory, while the last indicates that while there were no locking failures, CPU-hotplug problems were detected. -Also see: Documentation/RCU/torture.txt +Also see: Documentation/RCU/torture.rst
MAINTAINERS +2 -2
@@ -14424,7 +14424,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev F: Documentation/RCU/ F: include/linux/rcu* F: kernel/rcu/ -X: Documentation/RCU/torture.txt +X: Documentation/RCU/torture.rst X: include/linux/srcu*.h X: kernel/rcu/srcu*.c
@@ -17273,7 +17273,7 @@ M: Josh Triplett <[email protected]> L: [email protected] S: Supported T: git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev -F: Documentation/RCU/torture.txt +F: Documentation/RCU/torture.rst F: kernel/locking/locktorture.c F: kernel/rcu/rcuperf.c F: kernel/rcu/rcutorture.c
kernel/rcu/rcutorture.c +1 -1
@@ -7,7 +7,7 @@* Authors: Paul E. McKenney <[email protected]> * Josh Triplett <[email protected]> * -* See also: Documentation/RCU/torture.txt +* See also: Documentation/RCU/torture.rst */ #define pr_fmt (fmt) fmt
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 6/10 docs: RCU: Convert rcuref.txt to ReST
In reply to Paul E. McKenneyFrom: Mauro Carvalho Chehab <[email protected]>
- 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.
---
Documentation/RCU/index.rst | 1 +
Documentation/RCU/{rcuref.txt => rcuref.rst} | 199 ++++++++++++++-------------
2 files changed, 104 insertions(+), 96 deletions(-)
rename Documentation/RCU/{rcuref.txt => rcuref.rst} (50%)Documentation/RCU/index.rst +1 -0
@@ -18,6 +18,7 @@ RCU concepts whatisRCU rcu rculist_nulls + rcuref torture listRCU NMI-RCU
Documentation/RCU/rcuref.rst renamed from Documentation/RCU/rcuref.txt +103 -96
233 lines not on this page · raw message
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 7/10 docs: RCU: Convert stallwarn.txt to ReST
In reply to Paul E. McKenneyFrom: Mauro Carvalho Chehab <[email protected]>
- Add a SPDX header;
- Adjust document and section titles;
- Fix list markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.
---
Documentation/RCU/index.rst | 1 +
Documentation/RCU/{stallwarn.txt => stallwarn.rst} | 55 +++++++++++++---------
kernel/rcu/tree_stall.h | 4 +-
3 files changed, 37 insertions(+), 23 deletions(-)
rename Documentation/RCU/{stallwarn.txt => stallwarn.rst} (90%)Documentation/RCU/index.rst +1 -0
@@ -20,6 +20,7 @@ RCU concepts rculist_nulls rcuref torture + stallwarn listRCU NMI-RCU UP
Documentation/RCU/stallwarn.rst renamed from Documentation/RCU/stallwarn.txt +34 -21
193 lines not on this page · raw message
kernel/rcu/tree_stall.h +2 -2
@@ -468,7 +468,7 @@ static void print_other_cpu_stall(unsigned long gp_seq, unsigned long gps)/* * OK, time to rat on our buddy... -* See Documentation/RCU/stallwarn.txt for info on how to debug +* See Documentation/RCU/stallwarn.rst for info on how to debug * RCU CPU stall warnings. */ pr_err ("INFO: %s detected stalls on CPUs/tasks:\n" , rcu_state.name);
@@ -535,7 +535,7 @@ static void print_cpu_stall(unsigned long gps)/* * OK, time to rat on ourselves... -* See Documentation/RCU/stallwarn.txt for info on how to debug +* See Documentation/RCU/stallwarn.rst for info on how to debug * RCU CPU stall warnings. */ pr_err ("INFO: %s self-detected stall on CPU\n" , rcu_state.name);
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 8/10 docs: RCU: Don't duplicate chapter names in rculist_nulls.rst
In reply to Paul E. McKenneyFrom: Mauro Carvalho Chehab <[email protected]>
Since changeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst"), auto-references for chapters are generated. This is a nice feature, but has a drawback: no chapters can have the same sumber.
So, we need to add two higher hierarchy chapters on this document, in order to avoid such duplication.
--- Documentation/RCU/rculist_nulls.rst | 6 ++++++ 1 file changed, 6 insertions(+)
Documentation/RCU/rculist_nulls.rst +6 -0
@@ -10,6 +10,9 @@ objects using SLAB_TYPESAFE_BY_RCU allocations. Please read the basics in Documentation/RCU/listRCU.rst +Using 'nulls' +============= + Using special makers (called 'nulls') is a convenient way to solve following problem :
@@ -126,6 +129,9 @@ 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 smp_wmb() in insert function.
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 9/10 doc: Timer problems can cause RCU CPU stall warnings
In reply to Paul E. McKenneyFrom: "Paul E. McKenney" <[email protected]>
Over the past few years, there have been several cases where timekeeping bugs have caused RCU CPU stall warnings, particularly during hardware bringup. This commit therefore adds such bugs to the list of things that can result in RCU CPU stall warnings.
--- Documentation/RCU/stallwarn.rst | 7 +++++++ 1 file changed, 7 insertions(+)
Documentation/RCU/stallwarn.rst +7 -0
@@ -87,6 +87,13 @@ warnings: problem really has happened, and seems to be most likely to result in RCU CPU stall warnings for CONFIG_NO_HZ_COMMON=n kernels. +- A hardware or software issue that prevents time-based wakeups + from occurring. These issues can range from misconfigured or + buggy timer hardware through bugs in the interrupt or exception + path (whether hardware, firmware, or software) through bugs + in Linux's timer subsystem through bugs in the scheduler, and, + yes, even including bugs in RCU itself. + - A bug in the RCU implementation. - A hardware failure. This is quite unlikely, but has occurred
Signature · 1 line
2.9.5
[email protected]
maintainerPATCH 10/10 doc: Tasks RCU must protect instructions before trampoline
In reply to Paul E. McKenneyFrom: "Paul E. McKenney" <[email protected]>
Protecting the code in a trampoline can also require protecting a number of instructions prior to actually entering the trampoline. For example, these earlier instructions might be computing the address of the trampoline. This commit therefore updates RCU's requirements to record this for posterity.
--- Documentation/RCU/Design/Requirements/Requirements.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/RCU/Design/Requirements/Requirements.rst +6 -1
@@ -2583,7 +2583,12 @@ not work to have these markers in the trampoline itself, because there would need to be instructions following ``rcu_read_unlock()``. Although ``synchronize_rcu()`` would guarantee that execution reached the ``rcu_read_unlock()``, it would not be able to guarantee that execution -had completely left the trampoline. +had completely left the trampoline. Worse yet, in some situations +the trampoline's protection must extend a few instructions *prior* to +execution reaching the trampoline. For example, these few instructions +might calculate the address of the trampoline, so that entering the +trampoline would be pre-ordained a surprisingly long time before execution +actually reached the trampoline itself. The solution, in the form of `Tasks RCU <https://lwn.net/Articles/607117/>`__, is to have implicit read-side
Signature · 1 line
2.9.5